{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-section-pages","path":"/generators/section-pages","type":"module","module":"generators-section-pages","title":"Section pages","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `section-pages` generator adds a page for each section of every module,\nnext to the full module page, so readers can open a single class or method on\nits own. Use it when your modules are long reference pages.\n\n**Target:** `section-pages` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `<module>/<section>.html`, through `html`","summary":"The `section-pages` generator adds a page for each section of every module, next to the full module page, so readers can open a single class or method on its own. Use it when your modules are long reference pages.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t section-pages -i \"doc/api/*.md\" -o out\n```\n\nEvery module keeps its full page (`fs.html`) and gets one page per section in\na directory of its own (`fs/callback-api.html`). The full page keeps its\ncontent; only its sidebar and previous/next links change to include the\nsection pages. What the run writes depends on the targets you pass with\n`section-pages`:\n\n| You request                   | You get                                                |\n| ----------------------------- | ------------------------------------------------------ |\n| `-t section-pages`            | The website and `sitemap.xml`, both with section pages |\n| `-t html -t section-pages`    | The website only                                       |\n| `-t sitemap -t section-pages` | `sitemap.xml` only                                     |\n\n> \\[!IMPORTANT]\n> The [sitemap](https://doc-kit.nodejs.org/generators/sitemap) lists absolute\n> URLs, so set `baseURL` in your configuration file whenever the run includes\n> it. Without it, every URL keeps a literal `{baseURL}` placeholder.","summary":"Every module keeps its full page (`fs.html`) and gets one page per section in a directory of its own (`fs/callback-api.html`). The full page keeps its content; only its sidebar and previous/next links change to include the section pages. What the run writes depends on the targets you pass with `section-pages`:","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t section-pages -i \"doc/api/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `section-pages` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  'section-pages': {\n    // Also start pages at ### classes, methods, events and globals\n    maxDepth: 3,\n    exclude: ['deprecations'],\n  },\n};\n```\n\n* `maxDepth` {number} The deepest heading level that can start a section\n  page: `##` headings can, and so can classes, methods, events and globals\n  from `###` down to this level. Values below `2` split nothing.\n  **Default:** `2`.\n* `exclude` {string[]} Modules never to split, by their `api` name (`fs` for\n  `fs.md`). **Default:** `[]`.\n\nWith this configuration, Node.js's `fs.md` comes out as:\n\n```text\nout/\n├── fs.html                   the full module page, same content\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    └── ...\n```","summary":"Options go in the `section-pages` section of the configuration file:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  'section-pages': {\n    // Also start pages at ### classes, methods, events and globals\n    maxDepth: 3,\n    exclude: ['deprecations'],\n  },\n};"},{"language":"text","displayName":null,"code":"out/\n├── fs.html                   the full module page, same content\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    └── ..."}],"children":[]},{"kind":"section","id":"what-gets-its-own-page","name":"What gets its own page","title":"What gets its own page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Within a module, a new section page starts at:\n\n* every `##` heading, and\n* every heading from `###` down to `maxDepth` that is a class, method, event or\n  global (an entry marked `type: global`), such as `### fs.readFile()`.\n\nEverything else stays on the page of the closest heading above it:\n\n* prose sub-sections below `##`, such as `#### File descriptors`;\n* constructors, properties and static methods below `##`;\n* at any depth, the members of a class, so a class page lists its whole API\n  (`### Class: fs.Dir` keeps `#### dir.close()`).\n\nA section only gets a page when it documents an API entry, in its own heading\nor any heading below it. Pure prose (`## Introduction`, `## Notes`) reads best\nin the context of the full page and stays there. A prose heading whose\nsub-sections are API entries (`## Callback API`) still gets a page, so the\nsidebar can nest them under it.\n\nThe module's introduction, everything before the first heading that starts a\npage, is only on the full page. A module isn't split when it would get fewer\nthan two section pages (which includes every module that documents no API\nentry), when it's listed in `exclude`, or when it has no `#` heading.","summary":"Within a module, a new section page starts at:","examples":[],"children":[]},{"kind":"section","id":"file-names","name":"File names","title":"File names","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A section page's file name comes from its heading:\n\n* API names keep their case and drop the module's own prefix: `fs.readFile()`\n  becomes `fs/readFile.html`, and `Class: fs.Dir` becomes `fs/Dir.html`.\n* Names from another namespace keep it: `fs/fsPromises.readFile.html`.\n* Prose headings, and API names that aren't safe file names, are slugged:\n  `fs/callback-api.html`.\n* A name repeated within a module gets a number (`close.html`,\n  `close-2.html`). The comparison ignores case, so the output is safe on\n  case-insensitive file systems.\n\nHeading anchors don't change, so\n`fs/readFile.html#fsreadfilepath-options-callback` and\n`fs.html#fsreadfilepath-options-callback` point at the same section.","summary":"A section page's file name comes from its heading:","examples":[],"children":[]},{"kind":"section","id":"on-a-section-page","name":"On a section page","title":"On a section page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A section page renders like any other page, with the same layout, sidebar,\ntable of contents and search. The section's heading becomes the page's main\nheading, and its sub-headings move up with it. Also:\n\n* **Sidebar:** while you view a split module or one of its section pages, the\n  module's entry expands into its sections, nested by heading level, with the\n  module repeated as the first item.\n* **Previous and next:** on a split module and its section pages, the links\n  step through the module page and its section pages in document order,\n  instead of the sidebar order.\n* **Meta bar:** \"Part Of\" links back to the section's place on the full page.\n  \"View As\", \"Edit this page\" and the version picker point at the module's\n  files and pages. \"Added In\" shows the section's own version, falling back to\n  the module's.\n* **Links:** a fragment link follows its section to whichever page it ended up\n  on (anchors in the module's introduction point at the full page). Relative\n  links, including type links, are re-based so they still resolve from the\n  section page's directory. Absolute URLs don't change.","summary":"A section page renders like any other page, with the same layout, sidebar, table of contents and search. The section's heading becomes the page's main heading, and its sub-headings move up with it. Also:","examples":[],"children":[]},{"kind":"section","id":"data-for-custom-themes","name":"Data for custom themes","title":"Data for custom themes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Every entry on a section page carries a `chunk` property that describes where\nit came from:\n\n* `api` {string} The module's `api` (`fs`).\n* `path` {string} The module's `path` (`/fs`).\n* `slug` {string} The section's anchor on the full page.\n* `index` {number} The section's position within the module, in document\n  order.\n* `depth` {number} The level of the section's heading on the full page.\n\nThe entry's own `api`, `path` and `basename` are the section page's\n(`fs-readFile`, `/fs/readFile`, `readFile`). The first entry also gets a\n`title`, used as the page title and sidebar label (`fs.readFile`).\n\nTheme components receive this as `metadata.chunk`. The `chunks` export of\n[`#theme/config`](https://doc-kit.nodejs.org/generators/html#theme-config-module)\nmaps each split module's path to its label and section tree, which the\nbuilt-in sidebar and previous/next links use.","summary":"Every entry on a section page carries a `chunk` property that describes where it came from:","examples":[],"children":[]},{"kind":"section","id":"how-it-works","name":"How it works","title":"How it works","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`section-pages` doesn't render anything itself. It reads the API entries,\nkeeps them all, and appends a copy of each section's entries for every module,\nre-homed under the section page's own `api` and `path`. It names `html` and\n`sitemap` as its\n[dependents](https://doc-kit.nodejs.org/creating-generators#declaring-a-dependent),\nso the pipeline splices it in where each of them reads `metadata`:\n\n* in the `html` pipeline, between `metadata` and\n  [`jsx-ast`](https://doc-kit.nodejs.org/generators/jsx-ast), so the website\n  renders the section pages like any other;\n* directly in front of `sitemap`, so the section pages are listed.\n\nNo other generator sees the section pages. The search index, `llms.txt` and\nthe JSON outputs read `metadata` directly, so they keep pointing at the full\npages (which carry the same anchors) and nothing is indexed twice.","summary":"`section-pages` doesn't render anything itself. It reads the API entries, keeps them all, and appends a copy of each section's entries for every module, re-homed under the section page's own `api` and `path`. It names `html` and `sitemap` as its dependents, so the pipeline splices it in where each of them reads `metadata`:","examples":[],"children":[]},{"kind":"section","id":"trade-offs","name":"Trade-offs","title":"Trade-offs","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* Section pages repeat content that's also on the full page, so the site has\n  more pages and takes longer to build.\n* No redirects are generated from `fs.html#anchor` to a section page. The full\n  page still exists, so existing links keep working.\n* Section pages don't get `.json` or `.md` renderings of their own; their\n  \"View As\" links lead to the module's.\n* Section pages stay out of the sidebar's page list (they only appear nested\n  under the module you're viewing) and out of `all.html`.","summary":"","examples":[],"children":[]}]}