{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-llms-txt","path":"/generators/llms-txt","type":"module","module":"generators-llms-txt","title":"llms.txt","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `llms-txt` generator writes an [`llms.txt`](https://llmstxt.org/) file: a\nMarkdown index of your docs that links to each page with a one-line\ndescription, so language models and AI tools can find their way around. Add it\nwhen you publish your docs on the web.\n\nThis page also covers [llms-full.txt](#llms-fulltxt) (`llms-txt-full`), which\nputs the Markdown of every page in one file.\n\n**Target:** `llms-txt` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `llms.txt`","summary":"The `llms-txt` generator writes an `llms.txt` file: a Markdown index of your docs that links to each page with a one-line description, so language models and AI tools can find their way around. Add it when you publish your docs on the web.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The links in `llms.txt` are absolute URLs, so set `baseURL` to where your docs\nare published. 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://example.com',\n  },\n};\n```\n\n```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\nnpx doc-kit generate -t llms-txt -i \"docs/**/*.md\" -o out\n```\n\nFor a project named `my-lib` with `docs/index.md` and `docs/guide/usage.md`,\nthis writes:\n\n```text displayName=\"out/llms.txt\"\n# my-lib Documentation\n\n> API documentation for my-lib.\n\nBelow are the sections of the API documentation. Look out especially towards the links that point towards guidance/introduction to the structure of this documentation.\n\n## API Documentations\n- [Usage](https://example.com/guide/usage.md): How to call my-lib from your code.\n- [My library](https://example.com/index.md): A small library for working with strings.\n```\n\n> \\[!WARNING]\n> Without a `baseURL`, the links keep a literal `{baseURL}` (for example\n> `{baseURL}/guide/usage.md`), and nothing warns you about it.","summary":"The links in `llms.txt` are absolute URLs, so set `baseURL` to where your docs are published. 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://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 llms-txt -i \"docs/**/*.md\" -o out"},{"language":"text","displayName":"out/llms.txt","code":"# my-lib Documentation\n\n> API documentation for my-lib.\n\nBelow are the sections of the API documentation. Look out especially towards the links that point towards guidance/introduction to the structure of this documentation.\n\n## API Documentations\n- [Usage](https://example.com/guide/usage.md): How to call my-lib from your code.\n- [My library](https://example.com/index.md): A small library for working with strings."}],"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 `llms-txt` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```js displayName=\"doc-kit.config.mjs\"\nimport { join } from 'node:path';\n\nexport default {\n  'llms-txt': {\n    templatePath: join(import.meta.dirname, 'llms-template.txt'),\n    pageURL: '{baseURL}/docs{path}.md',\n  },\n};\n```\n\n* `templatePath` {string} The text file `llms.txt` starts with (see\n  [The template](#the-template)). A relative path resolves against the\n  directory you run doc-kit from. **Default:** the bundled `template.txt`.\n* `pageURL` {string} URL template for each page's link. `{path}` is the page's\n  path, without its extension and starting with a slash. **Default:**\n  `'{baseURL}{path}.md'`.\n* `output` {string} The directory to write `llms.txt` to. Without one, nothing\n  is written. **Default:** from `global.output` (`--output`).\n\nLike every generator section, it can also override a global option, such as\n`baseURL` or `project`, for this generator alone.","summary":"Options go in the `llms-txt` section of the configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"import { join } from 'node:path';\n\nexport default {\n  'llms-txt': {\n    templatePath: join(import.meta.dirname, 'llms-template.txt'),\n    pageURL: '{baseURL}/docs{path}.md',\n  },\n};"}],"children":[]},{"kind":"section","id":"what-it-lists","name":"What it lists","title":"What it lists","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`llms.txt` has one line for each top-level (`#`) heading in your sources, as\n`- [Heading](URL): Description`:\n\n* **Heading** is the heading's text. A page without a `#` heading isn't listed,\n  and a page with several gets a line for each.\n* **URL** is `pageURL` filled in for the page. `{path}` is the source file's\n  path relative to the base of the input glob: with `-i \"docs/**/*.md\"`,\n  `docs/guide/usage.md` becomes `/guide/usage`.\n* **Description** is the page's `llm_description` when it has one. Otherwise\n  it's the first paragraph between the heading and the next heading, on one\n  line: inline code, bold and italics keep their Markdown, and links become\n  plain text. Without such a paragraph, it's empty.\n\nIf your opening paragraph doesn't make a good summary on its own, write one for\nmodels with the\n[`llm_description` directive](https://doc-kit.nodejs.org/specification#624-llm_description),\nright after the heading it describes:\n\n```markdown displayName=\"docs/guide/usage.md\"\n# Usage\n\n<!-- llm_description=How to call my-lib from your code. -->\n```\n\n[Section pages](https://doc-kit.nodejs.org/generators/section-pages) aren't\nlisted: `llms.txt` links to the full pages.","summary":"`llms.txt` has one line for each top-level (`#`) heading in your sources, as `- [Heading](URL): Description`:","examples":[{"language":"markdown","displayName":"docs/guide/usage.md","code":"# Usage\n\n<!-- llm_description=How to call my-lib from your code. -->"}],"children":[]},{"kind":"section","id":"the-template","name":"The template","title":"The template","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`llms.txt` is the template's text followed directly by the list of links, so\nend the template with a newline. This is the default:\n\n```text displayName=\"template.txt\"\n# {project} Documentation\n\n> API documentation for {project}.\n\nBelow are the sections of the API documentation. Look out especially towards the links that point towards guidance/introduction to the structure of this documentation.\n\n## API Documentations\n```\n\nThe format at [llmstxt.org](https://llmstxt.org/) expects a `#` title with\nyour project's name, then a `>` summary, then `##` sections of links. A\ntemplate of your own can describe your project better and add links of its own\nabove the generated list.\n\nPlaceholders take the value of that option from the generator's configuration,\nwhich includes every global option:\n\n| Placeholder    | Value                                                                                               |\n| -------------- | --------------------------------------------------------------------------------------------------- |\n| `{project}`    | `project`: the `name` in your `package.json`, unless you set it                                     |\n| `{version}`    | `version` (`--version`): the Node.js version running doc-kit, unless you set your project's version |\n| `{repository}` | `repository`, as `owner/name`                                                                       |\n| `{baseURL}`    | `baseURL`                                                                                           |\n| `{ref}`        | `ref` (`--git-ref`): `HEAD` unless you set it                                                       |\n\nA placeholder without a value is left as written. To use a fallback instead,\nwrite `{name|fallback}`, where the fallback is a single word (letters, digits\nand underscores). The same placeholders work in `pageURL`, along with\n`{path}`.","summary":"`llms.txt` is the template's text followed directly by the list of links, so end the template with a newline. This is the default:","examples":[{"language":"text","displayName":"template.txt","code":"# {project} Documentation\n\n> API documentation for {project}.\n\nBelow are the sections of the API documentation. Look out especially towards the links that point towards guidance/introduction to the structure of this documentation.\n\n## API Documentations"}],"children":[]},{"kind":"section","id":"serving-pages-as-markdown","name":"Serving pages as Markdown","title":"Serving pages as Markdown","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The default `pageURL` links to a `.md` file at each page's path\n(`/guide/usage.md` next to `/guide/usage.html`), as llmstxt.org proposes,\nsince Markdown is easier for language models to read than HTML. doc-kit\ndoesn't write those files, so copy your sources into the output. With the\n[website](https://doc-kit.nodejs.org/generators/html), its `pathsToCopy` option\ndoes it:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html', 'llms-txt'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n    baseURL: 'https://example.com',\n  },\n  html: {\n    // Copies the contents of docs/ into out/\n    pathsToCopy: ['public', { docs: '.' }],\n  },\n};\n```\n\nSetting `pathsToCopy` replaces its default list (`assets`, `public` and\n`static`), so keep the ones you use, as `public` is kept here. doc-kit's own\nsite builds its [`llms.txt`](https://doc-kit.nodejs.org/llms.txt) this way.\nIf you don't serve Markdown, link to the HTML pages instead with\n`pageURL: '{baseURL}{path}.html'`.","summary":"The default `pageURL` links to a `.md` file at each page's path (`/guide/usage.md` next to `/guide/usage.html`), as llmstxt.org proposes, since Markdown is easier for language models to read than HTML. doc-kit doesn't write those files, so copy your sources into the output. With the website, its `pathsToCopy` option does it:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html', 'llms-txt'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n    baseURL: 'https://example.com',\n  },\n  html: {\n    // Copies the contents of docs/ into out/\n    pathsToCopy: ['public', { docs: '.' }],\n  },\n};"}],"children":[]},{"kind":"section","id":"llms-fulltxt","name":"llms-full.txt","title":"llms-full.txt","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `llms-txt-full` generator writes the Markdown of every page into one\n`llms-full.txt` file, each page after its URL, so a language model can read\nall of your docs in a single request. Pair it with `llms.txt`, which only\nlinks to each page.\n\n**Target:** `llms-txt-full` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `llms-full.txt`","summary":"The `llms-txt-full` generator writes the Markdown of every page into one `llms-full.txt` file, each page after its URL, so a language model can read all of your docs in a single request. Pair it with `llms.txt`, which only links to each page.","examples":[],"children":[{"kind":"section","id":"using-llms-fulltxt","name":"Using llms-full.txt","title":"Using llms-full.txt","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Set `global.baseURL` as for [`llms.txt`](#usage), since each page's URL starts\nwith it, then run:\n\n```bash\nnpx doc-kit generate -t llms-txt -t llms-txt-full -i \"docs/**/*.md\" -o out\n```","summary":"Set `global.baseURL` as for `llms.txt`, since each page's URL starts with it, then run:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t llms-txt -t llms-txt-full -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring-llms-fulltxt","name":"Configuring llms-full.txt","title":"Configuring llms-full.txt","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `llms-txt-full` section of the configuration file:\n\n* `pageURL` {string} URL template written before each page. `{path}` is the\n  page's extensionless path, starting with a slash (`/fs`), and any other\n  option of the generator, global ones included, can be used too, such as\n  `{baseURL}` or `{project}`. It's set apart from `llms-txt.pageURL`, which\n  has the same default. **Default:** `'{baseURL}{path}.md'`.\n* `output` {string} The directory to write `llms-full.txt` to. Without one,\n  nothing is written. **Default:** from `global.output` (`--output`).\n* `markdown` {Object} [Markdown plugins](https://doc-kit.nodejs.org/configuration#markdown-plugins)\n  for this generator, added after the global ones.\n  * `remarkPlugins` {Array} Plugins of the processor that writes each page\n    back to Markdown. Pages are only serialized here, so these plugins change\n    how the Markdown is written (`remark-stringify` settings, syntax\n    extensions), not the content: their transforms don't run.\n\nThe default URLs point at each page's Markdown file, which none of the\nbuilt-in generators write: copy your sources into the output, as in\n[Serving pages as Markdown](#serving-pages-as-markdown), or set `pageURL` to\n`'{baseURL}{path}.html'` to point at the website's pages.","summary":"Options go in the `llms-txt-full` section of the configuration file:","examples":[],"children":[]},{"kind":"section","id":"what-the-file-holds","name":"What the file holds","title":"What the file holds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Every page read from your sources, one after another. Each starts with a `url`\nblock between `---` lines, built from `pageURL`, followed by the page's\nMarkdown. For this page and a `path.md` next to it:\n\n```md displayName=\"docs/fs.md\"\n# File system\n\n<!-- YAML\nadded: v1.0.0\n-->\n\nThe `fs` module reads and writes files. Paths can be built with\n[`path.join()`][join].\n\n### `fs.readFile(path)`\n\n- `path` {string|URL} The file to read.\n- Returns: {Promise<Buffer>}\n\n[join]: ./path.md#pathjoinparts\n```\n\n`llms-full.txt` holds:\n\n```text displayName=\"out/llms-full.txt\"\n---\nurl: https://docs.example.com/fs.md\n---\n# File system\n\nThe `fs` module reads and writes files. Paths can be built with\n[`path.join()`](./path.html#pathjoinparts).\n\n### `fs.readFile(path)`\n\n* `path` {string | URL} The file to read.\n* Returns: {Promise<Buffer>}\n\n---\nurl: https://docs.example.com/path.md\n---\n# Path\n\n### `path.join(...parts)`\n\nJoins path segments.\n```\n\nThe Markdown is rebuilt from the\n[API entries](https://doc-kit.nodejs.org/generators/metadata), not copied from\nyour files, so it differs from the sources in a few ways:\n\n* Links to `.md` files point to the `.html` pages.\n* Reference-style links become inline links, and their definitions are\n  dropped.\n* Formatting is normalized: bullet lists and emphasis use `*`, strong text\n  uses `**`, and a page without a heading starts with an empty `#`.\n* `<!-- YAML -->` comments are left out.\n* Type annotations are rewritten with spaces around `|` (`{string|URL}`\n  becomes `{string | URL}`). MDX pages keep their JSX.","summary":"Every page read from your sources, one after another. Each starts with a `url` block between `---` lines, built from `pageURL`, followed by the page's Markdown. For this page and a `path.md` next to it:","examples":[{"language":"md","displayName":"docs/fs.md","code":"# File system\n\n<!-- YAML\nadded: v1.0.0\n-->\n\nThe `fs` module reads and writes files. Paths can be built with\n[`path.join()`][join].\n\n### `fs.readFile(path)`\n\n- `path` {string|URL} The file to read.\n- Returns: {Promise<Buffer>}\n\n[join]: ./path.md#pathjoinparts"},{"language":"text","displayName":"out/llms-full.txt","code":"---\nurl: https://docs.example.com/fs.md\n---\n# File system\n\nThe `fs` module reads and writes files. Paths can be built with\n[`path.join()`](./path.html#pathjoinparts).\n\n### `fs.readFile(path)`\n\n* `path` {string | URL} The file to read.\n* Returns: {Promise<Buffer>}\n\n---\nurl: https://docs.example.com/path.md\n---\n# Path\n\n### `path.join(...parts)`\n\nJoins path segments."}],"children":[]}]}]}