Skip to content

Latest commit

 

History

History
113 lines (84 loc) · 7.48 KB

generators.md

File metadata and controls

113 lines (84 loc) · 7.48 KB

Generators

A generator makes one output from your documentation: the website, the search index, JSON, a man page. You pick generators by their target name with --target (-t) on the CLI, or with target in the configuration file. However many you pick, doc-kit parses your sources once and every generator reads that result.

npx @doc-kit/cli generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o out

Generators form a graph through dependsOn; picking html and orama-db runs only them and what they depend on, parsing your sources once

The website

From @doc-kit/generator-react, which you install next to the CLI.

Generator Target Output
Website html The site: server-rendered pages with interactive islands, bundled with Vite by default.
Section pages section-pages An extra page for each section of every module, added to the website and the sitemap.
Search index orama-db orama-db.json, the Orama index that the website's search box loads.
Sitemap sitemap sitemap.xml, listing the pages for search engines.
  • The search box shows only when the search index is built in the same run. Set showSearchBox in the html section to choose yourself.
  • section-pages adds its pages to whichever of html and sitemap you also ask for. Ask for it on its own and you get both.

For language models

From @doc-kit/generator-react.

Generator Target Output
llms.txt llms-txt An llms.txt index linking to each page.
llms-full.txt llms-txt-full llms-full.txt: every page's Markdown in one file, each after its URL.

Data

From @doc-kit/core, which comes with the CLI.

Generator Target Output
JSON json One JSON document per source file, described by a published schema.
JSON bundle json-all Every json document bundled into one all.json.
Debug JSON json-simple api-docs.json, a dump of the API entries for debugging the pipeline.

For Node.js

From @node-core/doc-kit, which you install next to the CLI. These serve the Node.js project's own build, release and tests, and their defaults match its layout, so they're mostly useful to Node.js and projects shaped like it.

Generator Target Output
Man page man-page A man page in mdoc format (node.1 by default), from a command-line reference page.
API links api-links apilinks.json, mapping each exported API to the line defining it in the sources.
Addon examples addon-verify The C++ addon examples' code blocks, written out with a binding.gyp for the tests.

Node.js's legacy formats

From @node-core/doc-kit-legacy, which you install next to the CLI. These write the HTML pages and JSON files of the Node.js API docs in the formats Node.js's original tooling made, for Node.js and the tools that read them. For your own docs, use the website and JSON generators above.

Generator Target Output
Legacy HTML legacy-html A classic Node.js HTML page per source file, with its assets/.
Legacy single-page HTML legacy-html-all all.html, every legacy HTML page one after another.
Legacy JSON legacy-json A classic Node.js JSON file per source file, with descriptions in HTML.
Legacy JSON bundle legacy-json-all all.json, the sections of every legacy JSON file merged into one file.

Pipeline stages

The generators above read from a few shared stages, which are generators too. A stage runs when a target needs it, once per run however many targets read it, and writes no files. You don't ask for stages yourself, but you configure them like any other generator: --type-map, for example, sets metadata.typeMap.

Stage Name Produces
Parsing Markdown ast The Markdown and MDX files in input, parsed into syntax trees in worker threads.
Parsing JavaScript ast-js The .js files in input, parsed with Acorn for api-links.
API entries metadata The flat list of API entries, one per heading with its kind, stability and history.
Page JSX jsx-ast Each page as a JSX program, which html renders.

jsx-ast comes from @doc-kit/generator-react; the other stages come from @doc-kit/core.

Options

Each generator reads its options from the configuration section named after it. See Generator options.

Your own

A target can also be an import specifier: a package export, or the path to a local file (starting with ., or absolute) whose default export is a generator. It runs alongside the built-in ones, and reads its options from the section named after its name.

npx @doc-kit/cli generate -t @my-scope/my-generator -t ./generators/rss.mjs ...

To write one, see Creating generators.