{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-sitemap","path":"/generators/sitemap","type":"module","module":"generators-sitemap","title":"Sitemap","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `sitemap` generator writes a `sitemap.xml` listing the pages of your site,\nso search engines can find them. Build it next to the\n[website](https://doc-kit.nodejs.org/generators/html) when you publish your\ndocs.\n\n**Target:** `sitemap` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `sitemap.xml`","summary":"The `sitemap` generator writes a `sitemap.xml` listing the pages of your site, so search engines can find them. Build it next to the website when you publish your docs.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A sitemap lists absolute URLs, so the generator needs your site's address,\n`baseURL`. There is no flag for it, so set it in your configuration file:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n global: {\n baseURL: 'https://docs.example.com',\n },\n};\n```\n\n```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t sitemap -i \"docs/**/*.md\" -o out\n```\n\nThis writes the site and `out/sitemap.xml`.\n\n> \\[!IMPORTANT]\n> Without a `baseURL`, every URL keeps the literal placeholder (for example\n> `{baseURL}/guide/intro.html`), and nothing warns you about it.","summary":"A sitemap lists absolute URLs, so the generator needs your site's address, `baseURL`. There is no flag for it, so set it in your configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n global: {\n baseURL: 'https://docs.example.com',\n },\n};"},{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t html -t sitemap -i \"docs/**/*.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 `sitemap` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n* `indexURL` {string} URL template for the site's index page.\n **Default:** `'{baseURL}/'`.\n* `pageURL` {string} URL template for each page. **Default:**\n `'{baseURL}{path}.html'`.\n* `baseURL` {string} Your site's address, without a trailing slash. Set it here\n to use a different one for the sitemap alone. **Default:** from\n `global.baseURL`.\n* `output` {string} The directory to write `sitemap.xml` to. Without one,\n nothing is written. **Default:** from `global.output` (`--output`).","summary":"Options go in the `sitemap` section of the configuration file:","examples":[],"children":[{"kind":"section","id":"url-templates","name":"URL templates","title":"URL templates","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"In `indexURL` and `pageURL`:\n\n* `{name}` is replaced by the option of that name, global options included,\n such as `{baseURL}`, `{version}` or `{project}`.\n* `{name|fallback}` uses `fallback` (letters, digits and `_` only) when the\n option isn't set.\n* `{path}`, in `pageURL` only, is the page's path relative to the base of the\n input glob, with a leading slash and no extension: with `-i \"docs/**/*.md\"`,\n `docs/guide/intro.md` has the path `/guide/intro`.\n\nA placeholder with no value and no fallback stays in the URL as written.\n`baseURL` goes in exactly as written, so `https://docs.example.com/` gives\n`https://docs.example.com//guide/intro.html`. Pass a string, not a `URL`\nobject: the configuration is copied to worker threads, which can't receive\none.\n\nThe default `pageURL` matches the files the website writes\n(`guide/intro.html`). If your host redirects those to extensionless URLs, as\nVercel with `cleanUrls` and Cloudflare Workers do, drop the extension so\nsearch engines don't crawl redirects (see\n[Page URLs](https://doc-kit.nodejs.org/publishing#page-urls)):\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n sitemap: {\n pageURL: '{baseURL}{path}',\n },\n};\n```\n\nFor docs published per version, give each build its own `baseURL`, such as\n`https://docs.example.com/v1.x`, as in\n[Publishing several versions](https://doc-kit.nodejs.org/publishing#publishing-several-versions),\nand both templates point into that version unchanged. If you put the version\nin the templates instead (`'{baseURL}/v{version}{path}.html'`), change\n`indexURL` as well (`'{baseURL}/v{version}/'`), and set `global.version` or\n`--version`: otherwise `{version}` is the version of the Node.js running\ndoc-kit.","summary":"In `indexURL` and `pageURL`:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n sitemap: {\n pageURL: '{baseURL}{path}',\n },\n};"}],"children":[]}]},{"kind":"section","id":"what-the-sitemap-lists","name":"What the sitemap lists","title":"What the sitemap lists","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* One URL for each level-one (`#`) heading in your input, built from\n `pageURL`. Give each page exactly one `#` heading: a page whose headings all\n start at `##` is left out, and a page with two `#` headings is listed twice.\n* The index page, built from `indexURL` and added last. It's added even when an\n `index.md` is already listed as `/index.html`.\n* With [section pages](https://doc-kit.nodejs.org/generators/section-pages),\n every section page as well. Add the target to the same run:\n `-t sitemap -t section-pages`.\n\nEach entry's `` is the day of the build (UTC). Its `` and\n`` are fixed:\n\n| Entry | URL from | `changefreq` | `priority` |\n| --------- | ---------- | ------------ | ---------- |\n| Each page | `pageURL` | `weekly` | `0.8` |\n| The index | `indexURL` | `daily` | `1.0` |\n\nFor `docs/index.md` and `docs/guide/intro.md`, with\n`baseURL: 'https://docs.example.com'`, the generator writes:\n\n```xml displayName=\"out/sitemap.xml\"\n\n\n\n https://docs.example.com/guide/intro.html\n 2026-10-26\n weekly\n 0.8\n\n\n https://docs.example.com/index.html\n 2026-10-26\n weekly\n 0.8\n\n\n https://docs.example.com/\n 2026-10-26\n daily\n 1.0\n\n\n\n```","summary":"Each entry's `` is the day of the build (UTC). Its `` and `` are fixed:","examples":[{"language":"xml","displayName":"out/sitemap.xml","code":"\n\n\n https://docs.example.com/guide/intro.html\n 2026-10-26\n weekly\n 0.8\n\n\n https://docs.example.com/index.html\n 2026-10-26\n weekly\n 0.8\n\n\n https://docs.example.com/\n 2026-10-26\n daily\n 1.0\n\n\n"}],"children":[]}]}