On this page

Generated Docs

Some pages are best written by a tool: the API reference of a library, from its code and comments, or a list of command line options. generate in clay.yaml runs such tools before every clay build, clay dev and clay check, so the generated pages are always up to date and part of the site like any other.

generate:
  - npx typedoc --plugin typedoc-plugin-markdown --entryFileName index --out docs/api src/index.ts

The commands run in the project folder, one after another. Whatever they write into docs/ becomes pages: in the navigation, the search, the link checks and the Markdown for agents.

Tip

This site generates its CLI reference from Clay’s own help, with a script of a few lines: scripts/cli-reference.mjs.

#API reference from code

Any tool that writes Markdown works:

TypeDoc with typedoc-plugin-markdown:

npm install --save-dev typedoc typedoc-plugin-markdown

generate:
  - npx typedoc --plugin typedoc-plugin-markdown --entryFileName index --out docs/api src/index.ts

gomarkdoc:

go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest

generate:
  - gomarkdoc --output docs/api/index.md ./...

pydoc-markdown:

pip install pydoc-markdown

generate:
  - pydoc-markdown -I src -m my_package > docs/api.md

Keep generated pages out of git. They are written fresh on every build:
.gitignore
```
docs/api/
```
in .gitignore.
Install the tool in CI too, before npx clay build --strict: as a dev dependency in package.json, or with a step of its own.
Write around it. An index.md in the folder gives the generated pages a title, an icon and an introduction, as long as the tool does not write one itself. See index pages.

#When a command fails

The build stops and shows the command’s last lines:

✖  Generating docs: npx typedoc --out docs/api src/index.ts
│  [error] The entry point src/index.ts does not exist
│  Failed with exit code 1
│
└  Build failed after 2.1s. Run "clay build --verbose" for the full output.

clay check --json reports the same lines as problems.

Note

The commands in clay.yaml run on every machine that builds the docs, like the scripts in package.json. Review changes to them like code.