{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-legacy-html","path":"/generators/legacy-html","type":"module","module":"generators-legacy-html","title":"Legacy HTML","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `legacy-html` generator writes Node.js's legacy HTML format: the API docs\nas the classic nodejs.org pages that Node.js's original documentation tooling\nbuilt, one per source file, with the same template, anchors and stylesheet.\nIt exists for Node.js; for a site of your own, use the\n[website](https://doc-kit.nodejs.org/generators/html) generator.","summary":"The `legacy-html` generator writes Node.js's legacy HTML format: the API docs as the classic nodejs.org pages that Node.js's original documentation tooling built, one per source file, with the same template, anchors and stylesheet. It exists for Node.js; for a site of your own, use the website generator.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The pages link to their source on GitHub and to their other versions on your\nsite, so set `repository` and `baseURL` under `global` in your configuration\nfile, or extend the [Node.js preset](https://doc-kit.nodejs.org/packages/node),\nwhich sets them, along with `changelog`, for Node.js. Then, from the root of a\nNode.js checkout:\n\n```bash\nnpx @doc-kit/cli generate -t legacy-html -i \"doc/api/*.md\" -o out \\\n --index doc/api/index.md --changelog CHANGELOG.md --version 24.1.0\n```\n\nThis writes a page per source file, named after its `api` identifier\n(`doc/api/fs.md` becomes `out/fs.html`), and copies the stylesheet, script and\nicons the pages load into `out/assets/`. Pages are written side by side\nwhatever directory their source is in, so `guide/usage.md` becomes\n`guide-usage.html`, which links to `guide/usage.md` miss. Keep your sources in\none flat directory, as Node.js's `doc/api/` is.\n\nEach page's header also links to `all.html` and to its JSON file, such as\n`fs.json`. Build them into the same directory with\n[`legacy-html-all`](https://doc-kit.nodejs.org/generators/legacy-html-all) and\n[`legacy-json`](https://doc-kit.nodejs.org/generators/legacy-json).","summary":"The pages link to their source on GitHub and to their other versions on your site, so set `repository` and `baseURL` under `global` in your configuration file, or extend the Node.js preset, which sets them, along with `changelog`, for Node.js. Then, from the root of a Node.js checkout:","examples":[{"language":"bash","displayName":null,"code":"npx @doc-kit/cli generate -t legacy-html -i \"doc/api/*.md\" -o out \\\n --index doc/api/index.md --changelog CHANGELOG.md --version 24.1.0"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* `ref` {string} The Git ref that the source links and the \"Edit on GitHub\"\n link point at. **Default:** `'main'`, which wins over `global.ref`, so\n `--git-ref` doesn't change it: set it here.\n* `pageURL` {string} URL template for each release in the \"Other versions\"\n picker. `{version}` is the release line, such as `v22.x`, and `{path}` is the\n page's path (`/fs`); see\n [templates](https://doc-kit.nodejs.org/configuration#generator-options).\n **Default:** `'{baseURL}/latest-{version}/api{path}.html'`.\n* `editURL` {string} URL template for the \"Edit on GitHub\" link, with the same\n placeholders. **Default:**\n `'https://github.com/{repository}/edit/{ref}/doc/api{path}.md'`.\n* `templatePath` {string} The HTML template each page is written into (see\n [The template](#the-template)). **Default:** the bundled `template.html`.\n* `additionalPathsToCopy` {string[]} Directories to copy into the output, each\n under its own name. Setting it replaces the default. **Default:** the bundled\n `assets` directory.\n\nIt also reads the\n[global options](https://doc-kit.nodejs.org/configuration#global-options):\n`changelog` sets the releases the \"Other versions\" picker lists, and `index`\nthe sidebar's order (without one, pages are listed by title, alphabetically).\n\nThe pages render Markdown with a fixed set of plugins, so a `markdown` section\nfor this generator is ignored with a warning.\n[Global remark plugins](https://doc-kit.nodejs.org/configuration#markdown-plugins)\nstill change the entries it reads.","summary":"It also reads the global options: `changelog` sets the releases the \"Other versions\" picker lists, and `index` the sidebar's order (without one, pages are listed by title, alphabetically).","examples":[],"children":[]},{"kind":"section","id":"what-a-page-holds","name":"What a page holds","title":"What a page holds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each page fills the template with its title, a table of contents of its\nheadings down to level 5, the sidebar, and its content, in which:\n\n* Each heading has a `#` link to its anchor, and a second anchor with the slug\n the original tooling gave it (`fs_fs_readfile_path_options_callback`), so old\n links still land on it.\n* Each section's metadata becomes a line under its heading: a \"Source Code\"\n link from `source_link`, the versions it was added, deprecated or removed\n in, its N-API version, and a collapsed \"History\" table of its `changes`.\n* Stability indexes become colored boxes, and their level also colors the\n heading's entry in the table of contents.\n* A `` comment adds a table of the\n stability of every page that has one, as in Node.js's `documentation.md`.\n* Code blocks are highlighted.\n* In MDX sources, JSX elements render as their children, and expressions are\n left out.","summary":"Each page fills the template with its title, a table of contents of its headings down to level 5, the sidebar, and its content, in which:","examples":[],"children":[]},{"kind":"section","id":"the-template","name":"The template","title":"The template","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The bundled template is the Node.js one: its title, canonical URL, logo and\nlinks are nodejs.org's. To change them, copy it and set `templatePath`. The\ngenerator replaces these placeholders:\n\n| Placeholder | Replaced with |\n| ------------------------ | ------------------------------------------------------------------------ |\n| `__SECTION__` | The page's title: its first heading, or its `api` capitalized. |\n| `__VERSION__` | `version` with a `v`, such as `v24.1.0`. |\n| `__FILENAME__`, `__ID__` | The page's `api` identifier, such as `fs`. |\n| `__TOC__` | The table of contents, in a `
`. |\n| `__TOC_PICKER__` | The table of contents again, as the header's \"Table of contents\" picker. |\n| `__GTOC__` | The sidebar, linking to every page. |\n| `__GTOC_PICKER__` | The sidebar again, as the header's \"Index\" picker. |\n| `__ALTDOCS__` | The \"Other versions\" picker. |\n| `__EDIT_ON_GITHUB__` | The \"Edit on GitHub\" link, from `editURL`. |\n| `__CONTENT__` | The page's content. |\n\n`__ID__`, `__SECTION__`, `__CONTENT__`, `__ALTDOCS__` and `__EDIT_ON_GITHUB__`\nare replaced where they first appear only; the others, everywhere.","summary":"The bundled template is the Node.js one: its title, canonical URL, logo and links are nodejs.org's. To change them, copy it and set `templatePath`. The generator replaces these placeholders:","examples":[],"children":[]}]}