Skip to main content

Documentation and examples

ProjectDirectoryRole
Library/ (pnpm)Its JSDoc generates the API reference
Examplesexamples/ (npm)The only source of code on this site – tested like library code
Docsdocs/ (npm)This site

Run the docs​

Run pnpm install in the repository root once. Then every docs script runs as pnpm docs:<script> from the root, or npm run <script> from docs/ (after npm ci):

TaskFrom the repository rootFrom docs/
Preview with live reloadpnpm docs:startnpm run start
Build into build/pnpm docs:buildnpm run build
Serve the buildpnpm docs:servenpm run serve
Generate the API reference (--force: even if unchanged)pnpm docs:apinpm run api
Type-checkpnpm docs:typechecknpm run typecheck
Lintpnpm docs:lintnpm run lint
Unit tests and sync checkspnpm docs:test:unitnpm run test:unit
Build, then check every page and linkpnpm docs:test:e2enpm run test:e2e
Everything CI checkspnpm docs:checknpm run check
Refresh the README's snippetspnpm docs:sync:markdownnpm run sync:markdown
Freeze the current docs as a versionpnpm docs:version:cutnpm run version:cut

After editing JSDoc in src/, run pnpm docs:api; the running preview picks it up.

Embed code​

Never write code in a page. Mark a region in an example:

examples/getting-started/payments-api.test.ts
it("registers the recorded stubs", () => {
expect(paymentsApi()).toBeInstanceOf(WiremockContainer);
});

it("fails fast on a fixture directory without mappings/", () => {
expect(() => new WiremockContainer().withMappings("./__mocks__/missing")).toThrow(
'WiremockContainer.withMappings: "__mocks__/missing/mappings" does not exist',
);
});

Source: examples/getting-started/payments-api.test.ts (lines 13–21)

Embed it with an empty block – the build fills it and links its source:

```ts file=getting-started/quick-start.e2e.test.ts#quick-start
```
  • The example names its page in a header comment: @see https://…/docs/<page>.
  • Shell commands (bash) may be written inline.
  • The root README holds copies, marked <!-- snippet: path#region --> – refresh them with pnpm docs:sync:markdown.

Update the docs with the library​

ChangeUpdate
InternalNothing – label the pull request no-docs-needed
Behaviour or an error messageThe guide, the examples asserting it, troubleshooting
New export, method or optionJSDoc with @see; an example with tests; a guide section embedding it; an API overview row
Deprecation@deprecated naming the replacement; a note in its guide
RemovalIts examples, guide sections and API overview row
Breaking changeAs above, plus a migration guide entry – the first one opens the next major (Versions)

Same pull request as the code. CONTRIBUTING.md lists what catches each omission.

What the checks enforce​

  • Every snippet reference, region, link and anchor resolves; every region is shown; pages hold no hand-written TypeScript, JavaScript or JSON.
  • Every example links to a page showing its folder.
  • Every export and public member is used in an example, named in a guide and listed in the API overview – checked with the TypeScript compiler.
  • JSDoc @examples are excerpts of examples; JSDoc @see links name existing pages.
  • TypeDoc fails on undocumented APIs; Docusaurus on broken links or anchors.

Versions​

One docs version per major, published from main. package.json's version decides what the site shows:

package.json/docsAlso
0.4.10.x–
1.0.0-next.20.x (frozen)/docs/next: 1.x (next), unreleased
1.0.01.x/docs/0.x (frozen)

The first breaking change of a major opens it:

pnpm docs:version:cut # freeze the 0.x docs
npm version premajor --preid next --no-git-tag-version # 0.4.1 → 1.0.0-next.0

pnpm version major releases it. Full procedure: release.md.