How to Contribute

Setup

git clone <repo-url>
cd antora-asciidoc-tracing
npm install
npm run build
npm test

Development workflow

npm run build          # Compile TypeScript (src/ → lib/)
npm test               # Run all tests (compiles test files first)
npm run test:coverage  # Run tests with c8 coverage
npm run lint           # Run biome checks
npm run format         # Auto-format with biome

Two TypeScript configurations:

  • tsconfig.json — production build: src/ → lib/

  • tsconfig.test.json — test build: src/ + test/ → lib/

The build script (scripts/build.js) copies templates, presets, and CJS extension files to lib/src/ for npm distribution.

Pre-commit hooks: biome lint + format via pre-commit.

Preview the example site

Build the full deployed site locally (Antora docs + blog + landing page + PDF + DOCX):

npm run preview    # same pipeline as CI, uses local content

This script (scripts/preview.js) replicates the CI pipeline in one command:

  1. Cleans public/

  2. Builds the Antora documentation site and blog (public/docs/)

  3. Generates PDFs and DOCX (public/pdf/) — skipped if ruby/pandoc is missing

  4. Copies the landing page (landing/ → public/)

After building, serve locally:

npx serve public

The CI workflow calls the same script with --ci to use the remote content source (antora-playbook-ci.yml) instead of the local one (antora-playbook.yml).

Blog

The blog is an Antora component (blog/) that renders alongside the docs. Posts are AsciiDoc files with :page-date: and :page-tags: attributes.

# Add a new post
cp blog/modules/ROOT/pages/2026-01-15-hello.adoc blog/modules/ROOT/pages/$(date +%Y-%m-%d)-my-post.adoc
# Edit content, update :page-date: and :page-tags:
node scripts/generate-blog-index.js    # Regenerate index page
npm run preview                        # Build and check locally

The index generator (scripts/generate-blog-index.js) scans blog/modules/ROOT/pages/*.adoc, extracts metadata, and writes index.adoc with a date-sorted listing. It’s called automatically by npm run preview and in CI.

Code style

  • TypeScript strict mode

  • ESM imports with .js extensions in import paths

  • JSDoc comments on public methods

  • No default exports (named exports only)

  • Biome for linting and formatting

Documentation style

Documentation follows the Documentation Style Guide — Diátaxis structure, one sentence per line, EARS requirements, and the voice rules there.

Commit conventions

This project follows Conventional Commits:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore, ci, perf

Common scopes: parser, cli, preset, matrix, neo4j, antora, config, graph

Testing

Tests use Mocha + Chai, written in TypeScript, compiled with tsconfig.test.json to lib/test/. Write tests:

import { expect } from 'chai';
import { RequirementsTraceabilityExtension } from '../src/index.js';

describe('MyFeature', () => {
  it('should do something', () => {
    const extension = new RequirementsTraceabilityExtension();
    extension.process(`...[#X, item, role=requirement]...`, { sourceFile: 'test.adoc' });
    expect(extension.getAllItems()).to.have.lengthOf(1);
  });
});

Run individual test files:

npx mocha 'lib/test/graph-and-api.test.js'

Build and release

npm run build        # Compile
npm test             # Verify all tests pass
npm version 0.7.0    # Bump version
npm publish          # Publish to npm

Related