{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"getting-started","path":"/getting-started","type":"module","module":"getting-started","title":"Getting started","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"This guide takes you from one Markdown file to a documentation site with\nsearch, in a few minutes. Run the commands from your project's root, next to\nits `package.json`.\n\n![doc-kit generate writes kittens.html, all.html, 404.html, assets/ and the search index to out/, which any static host serves as is](./diagrams/build-output.svg)","summary":"This guide takes you from one Markdown file to a documentation site with search, in a few minutes. Run the commands from your project's root, next to its `package.json`.","examples":[],"children":[{"kind":"section","id":"install","name":"Install","title":"Install","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Install the CLI, and the generators that build the site:\n\n```bash\nnpm install --save-dev @doc-kit/cli @doc-kit/generator-react\n```\n\n`@doc-kit/cli` gives you the `doc-kit` command and the core generators, such\nas `json`. `@doc-kit/generator-react` adds the website and what comes with it:\nthe search index, `llms.txt` and a sitemap.","summary":"Install the CLI, and the generators that build the site:","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @doc-kit/generator-react"}],"children":[]},{"kind":"section","id":"write-a-page","name":"Write a page","title":"Write a page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Create `docs/kittens.md`:\n\n```markdown displayName=\"docs/kittens.md\"\n# Kittens\n\nThe `kittens` module adopts, feeds, and pets kittens.\n\n## `kittens.adopt(name[, options])`\n\n<!-- YAML\nadded: v1.0.0\n-->\n\n- `name` {string} The kitten's name.\n- `options` {Object}\n  - `color` {string} Coat color. **Default:** `'tabby'`.\n- Returns: {Promise} Fulfills with the adopted kitten.\n\nAdopts a kitten, once the paperwork is done.\n```\n\nIt's regular Markdown, and reads as such on GitHub. doc-kit also reads the API\nin it: the heading is a method with its signature, the list holds its typed\nparameters, and the comment is its history.\n[Writing documentation](./writing-docs.html) covers the rest.\n\n> \\[!TIP]\n> Documenting a TypeScript or JavaScript project?\n> [`@doc-kit/typedoc`](./packages/typedoc.html) writes these pages from your\n> source code and its JSDoc comments; see\n> [Documenting TypeScript](./typescript.html).","summary":"Create `docs/kittens.md`:","examples":[{"language":"markdown","displayName":"docs/kittens.md","code":"# Kittens\n\nThe `kittens` module adopts, feeds, and pets kittens.\n\n## `kittens.adopt(name[, options])`\n\n<!-- YAML\nadded: v1.0.0\n-->\n\n- `name` {string} The kitten's name.\n- `options` {Object}\n  - `color` {string} Coat color. **Default:** `'tabby'`.\n- Returns: {Promise} Fulfills with the adopted kitten.\n\nAdopts a kitten, once the paperwork is done."}],"children":[]},{"kind":"section","id":"configure","name":"Configure","title":"Configure","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Create `doc-kit.config.mjs` next to your `package.json`:\n\n```js displayName=\"doc-kit.config.mjs\"\n/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */\nexport default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    project: 'Kittens',\n    version: '1.0.0',\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n};\n```\n\n* `target` lists the generators to run: `html` builds the site, and\n  `orama-db` its search index.\n* `input` takes glob patterns, and `output` is the directory to write to.\n* `project` and `version` go into page titles. Without them, doc-kit uses the\n  `name` in your `package.json` and the version of Node.js running it.\n\n`target`, `input`, `output` and `version` also have [CLI](./cli.html) flags,\nwhich win over the file. The [configuration reference](./configuration.html)\nlists every other option.","summary":"Create `doc-kit.config.mjs` next to your `package.json`:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */\nexport default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    project: 'Kittens',\n    version: '1.0.0',\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n};"}],"children":[]},{"kind":"section","id":"build-and-preview","name":"Build and preview","title":"Build and preview","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx doc-kit generate\n```\n\nThe site is written to `out/`: one page per Markdown file, plus `all.html`\nwith every page on one. Its pages load their scripts as modules and hydrate in\nthe browser, so serve them over HTTP rather than opening the files from disk:\n\n```bash\nnpx doc-kit preview\n```\n\nThen open <http://localhost:3000/kittens.html>. `preview` serves what\n`generate` built; pass it any `generate` option, such as\n`--config-file doc-kit.config.mjs`, and it builds first. Any other static\nserver works too, such as `npx serve out`.\n\n> \\[!TIP]\n> Add a `docs/index.md` and it becomes the site's home page, `index.html`.","summary":"The site is written to `out/`: one page per Markdown file, plus `all.html` with every page on one. Its pages load their scripts as modules and hydrate in the browser, so serve them over HTTP rather than opening the files from disk:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate"},{"language":"bash","displayName":null,"code":"npx doc-kit preview"}],"children":[]},{"kind":"section","id":"make-it-yours","name":"Make it yours","title":"Make it yours","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"To give the site your own logo and colors, add an `html` section to the\nconfiguration that points at a logo component and a stylesheet:\n\n```js displayName=\"doc-kit.config.mjs\"\nimport { join } from 'node:path';\n\n/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */\nexport default {\n  // target and global as above\n\n  html: {\n    // Your component in place of the project's name\n    imports: {\n      '#theme/Logo': join(import.meta.dirname, 'theme/Logo.jsx'),\n    },\n\n    // Bundled after doc-kit's own styles, so your rules win\n    stylesheets: [join(import.meta.dirname, 'theme/styles.css')],\n  },\n};\n```\n\n```jsx displayName=\"theme/Logo.jsx\"\nexport default () => <strong>Kittens</strong>;\n```\n\n```css displayName=\"theme/styles.css\"\n:root {\n  --color-brand-100: #f7f1fb;\n  --color-brand-200: #ead9fb;\n  --color-brand-300: #dbbdf9;\n  --color-brand-400: #c79bf2;\n  --color-brand-500: #b07ae6;\n  --color-brand-600: #9756d6;\n  --color-brand-700: #7d3cbe;\n  --color-brand-800: #642b9e;\n  --color-brand-900: #361b52;\n}\n```\n\n> \\[!NOTE]\n> Theme components are compiled for Preact, so `preact` has to resolve from\n> your project. npm usually hoists it there from `@doc-kit/generator-react`;\n> with pnpm, add it yourself with `pnpm add --save-dev preact`.\n\n[Customizing the site](./customization.html) covers the other parts of the page\nyou can replace, and the [Website generator](./generators/html.html) lists every\noption.","summary":"To give the site your own logo and colors, add an `html` section to the configuration that points at a logo component and a stylesheet:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"import { join } from 'node:path';\n\n/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */\nexport default {\n  // target and global as above\n\n  html: {\n    // Your component in place of the project's name\n    imports: {\n      '#theme/Logo': join(import.meta.dirname, 'theme/Logo.jsx'),\n    },\n\n    // Bundled after doc-kit's own styles, so your rules win\n    stylesheets: [join(import.meta.dirname, 'theme/styles.css')],\n  },\n};"},{"language":"jsx","displayName":"theme/Logo.jsx","code":"export default () => <strong>Kittens</strong>;"},{"language":"css","displayName":"theme/styles.css","code":":root {\n  --color-brand-100: #f7f1fb;\n  --color-brand-200: #ead9fb;\n  --color-brand-300: #dbbdf9;\n  --color-brand-400: #c79bf2;\n  --color-brand-500: #b07ae6;\n  --color-brand-600: #9756d6;\n  --color-brand-700: #7d3cbe;\n  --color-brand-800: #642b9e;\n  --color-brand-900: #361b52;\n}"}],"children":[]},{"kind":"section","id":"next-steps","name":"Next steps","title":"Next steps","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* [Writing documentation](./writing-docs.html): the conventions that turn\n  Markdown into an API reference.\n* [Customizing the site](./customization.html): navigation, components, MDX and\n  the bundler.\n* [Generators](./generators.html): JSON, `llms.txt`, a sitemap, and every\n  other output doc-kit can build.\n* [Publishing your docs](./publishing.html): hosting, caching and base URLs.\n* [Creating generators](./creating-generators.html): outputs of your own.","summary":"","examples":[],"children":[]}]}