Contributing

Use the Node version in .node-version and npm 12.0.2. Install dependencies with npm ci; the committed lifecycle allowlist is authoritative.

Development

Run npm run build, npm run typecheck, and npm test while changing the runtime. Source is strict TypeScript; generated ESM, CommonJS, declarations, and preset modules live in dist.

Run npm run lint:all for shared-config checks. Use npm run lint:fix and npm run lint:prettier:fix only when intentionally rewriting files. Native actionlint is required for workflow checks; Gitleaks and Lychee support the additional security and link commands.

Run npm run sync:rules:write and npm run docs:demos:write when changing options or presets. These commands build current source first; GIF regeneration requires agg 1.9.0. Their check counterparts compare output without modifying tracked files. Run npm run docs:build to compile the Docusaurus site and all three config inspectors. Every public API reflection must have TSDoc; the documentation build enforces 100% coverage.

Documentation layout

The landing page lives in docs/docusaurus/src/pages/index.tsx; src/css/custom.css supplies the shared theme and colored navigation. Hand-authored guides live in site-docs. Edit scripts/docs-catalog.mjs for badges and preset descriptions, then run npm run sync:rules:write to update the README sections, preset pages, gallery, and homepage data. The option table comes from the implementation. Keep the README's generation markers intact.

The docs build includes local search, public API documentation, and all three inspectors. npm run docs:check-links checks the expected routes, search index, preset links, demo assets, and inspector entrypoints. After layout changes, review desktop and mobile widths in both themes, keyboard navigation, search, demo playback, and direct inspector routes.

Validation

npm run release:verify runs the full local gate, including packed consumers on the minimum and current unified/remark boundaries. It does not publish. CI also exercises Linux, Windows, and macOS; minimum Node consumers are tested separately from the development install.

Use a type/description branch and the emoji/bracket commit convention in .github/agent-commit-message-instructions.md. Changes should include evidence that Markdown, trees, diagnostics, and exit codes remain unchanged.

On Windows, reproduce the console regression in a real PowerShell terminal with the code below. It tests the packed artifact on Node 22.0.0 with both host-version profiles, both output streams, Unicode filenames, ANSI colors, and shutdown summaries. The probe checks that reporter write methods and terminal columns stay unchanged. Inspect the output for intact élève-東京.md, spinner frames, and colored marks; the original code page is restored afterward.

$progressEncoding = [Console]::OutputEncoding
try {
    [Console]::OutputEncoding = [Text.Encoding]::GetEncoding(437)
    npm run test:compat:windows-console
} finally {
    [Console]::OutputEncoding = $progressEncoding
}

Release preparation

Keep the package version and exported metadata synchronized. Generate changelog history using the shared git-cliff configuration. The release workflow accepts an already committed version and protects against duplicate npm publication. Publication is a separately authorized operation. Configure npm trusted publishing for this repository, workflow release.yml, and environment npm when binding an environment. Dispatch the committed version from main; do not pass a token or disable provenance. If npm publication succeeds but the final GitHub Release job fails, rerun only failed jobs so artifact verification and release creation resume without repeating publication.

Dependency overrides

The ESLint 3.4.0 and remark 2.2.7 inspector bundles reapply root-relative favicon URLs after rendering. scripts/finalize-inspector-assets.mjs prefixes those known icon references with this site's deployment base. The remark bundle also references a missing remark/logo-square.svg; the script supplies that alias from its bundled favicon while leaving an upstream-supplied asset intact. Documentation checks reject these root-relative startup icons and require the alias. Remove these compatibility steps when the inspectors handle both cases themselves.

The same finalizer creates HTML entrypoints for each inspector's declared static routes. GitHub Pages does not provide a nested SPA fallback, so these entrypoints support refreshing or directly opening routes such as /remark-inspector/rules. The documentation gate requires an entrypoint for every declared route.

The docs toolchain currently pins vulnerable transitive ranges. Overrides select patched serialize-javascript and qs, and the CommonJS-compatible uuid 11 line used by SockJS only for v4(). Recheck these overrides when Docusaurus updates its dependencies. Docusaurus alone receives image-size-next@2.1.1 as an exact npm alias for image-size. The reviewed fork delta adds bounds and forward-progress checks for CVE-2025-71329 and CVE-2025-71330. It preserves the imageSizeFromFile API and MIT license, adds no runtime dependencies or install hooks, and is locked by tarball integrity. npm run test:docs-images exercises the actual Docusaurus-resolved parser against malformed ICNS/JXL/HEIF inputs in timeout-protected subprocesses and checks SVG/GIF/PNG dimensions. This override affects documentation builds only; remove it when Docusaurus adopts a maintained, patched parser.