The section-pages generator splits every documented module into per-section pages.\nIt leaves the full module page untouched and adds one extra page for each\nsection next to it:
out/\n├── fs.html the complete module page, exactly as before\n└── fs/\n ├── promises-api.html ## Promises API\n ├── FileHandle.html ### Class: FileHandle, with all of its members\n ├── fsPromises.readFile.html\n ├── callback-api.html ## Callback API\n ├── readFile.html ### fs.readFile(path[, options], callback)\n └── ...\nEach chunk page renders like any other page: same layout, sidebar, table of\ncontents, and search. On top of that:
\nnpx @doc-kit/cli generate -t section-pages -i \"doc/api/*.md\" -o out\nsection-pages does not render anything itself. It consumes the metadata\ngenerator's entries, and for each module appends copies of the entries of every\nsection, re-homed under the section's own api and path (fs/readFile).\nIt then declares the generators it is delivered through as its\ndependents:
html, where it is spliced between metadata and jsx-ast, so the web\ngenerators render the chunk pages as if they had always been there;sitemap, where it is spliced in front of the generator itself, so the\nchunk pages are listed.ast → metadata → section-pages → jsx-ast → html\n └─────────→ sitemap\nRequesting -t section-pages on its own therefore produces both. Requested together\nwith either of them (-t html -t section-pages), it only feeds the ones that run.
Other generators that read metadata — orama-db, llms-txt, and the JSON\noutputs — are deliberately left alone: search results and llms.txt keep\npointing at the full pages, which carry the same anchors, and nothing is\nindexed twice.
Within a module, a new chunk starts at:
\n## Callback API, ## Notes), andmaxDepth that documents an API entry — a method, class,\nconstructor, event, property, static method, or global (### fs.readFile()).Everything else stays in the chunk of the closest heading above it: prose\nsub-sections (#### File descriptors), and — regardless of depth — the members\nof a class, so that a class page lists its whole API (### Class: fs.Dir keeps\n#### dir.close()).
A section only becomes a chunk when it documents an API entry — its own\nheading, or one nested anywhere below it, is a method, class, constructor,\nevent, property, or static method. Pure prose (## Introduction, ## Notes,\nthe whole of \"About this documentation\") reads best in the context of the full\npage, and stays there. A prose-headed section whose sub-sections are API\nentries (## Callback API) is still a chunk, so that the sidebar can nest them\nunder it.
The module's own introduction (everything before the first depth-2 heading) is\nonly on the full page. Modules that would yield fewer than two chunks — which\nincludes every module that documents no API at all — and modules listed in\nexclude, are left alone.
A chunk's file name comes from its heading. API names keep their case, with the\nmodule's own prefix dropped, so fs.readFile() becomes fs/readFile.html and\nClass: fs.Dir becomes fs/Dir.html; names in another namespace keep it\n(fs/fsPromises.readFile.html). Prose headings are slugged\n(fs/callback-api.html). Duplicates within a module are suffixed\n(close.html, close-2.html), comparing case-insensitively so the output is\nsafe on case-insensitive file systems.
Heading anchors are unchanged, so fs/readFile.html#fsreadfilepath-options-callback\nand fs.html#fsreadfilepath-options-callback point at the same section.
maxDepth number The deepest heading level that may start a chunk.\nHeadings below it always stay with the section above them. Default: 2,\nwhich only splits at ## headings; the tree above is what 3 produces.exclude Array api names of modules that are never split, on top of the\nmodules that document no API entry. Default: [].// doc-kit.config.mjs\nexport default {\n target: ['section-pages'],\n 'section-pages': {\n // Also split at `###` headings that document an API entry\n maxDepth: 3,\n exclude: ['deprecations'],\n },\n};\nEvery entry of a chunk page carries a chunk property describing its origin,\nwhich the html UI uses for its navigation:
api string The api of the module the chunk was split from (fs).path string The path of the module (/fs).slug string The section's anchor on the full page.index number The chunk's position within the module, in document order.depth number The original depth of the chunk's heading.The chunk's first entry also gets a title — its sidebar label and page\ntitle (fs.readFile). The html generator exposes every module's section\ntree through the chunks export of\n#theme/config, for custom themes.
fs.html#anchor to a chunk page: the full\npage still exists, so existing links keep working, and both pages share\ntheir anchors..json or .md renderings of their own; their\n\"View As\" links lead to the module's.