{"$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\n[Writing documentation](./writing-docs.html) shows how to document an API in\nit.","summary":"Create `docs/kittens.md`:","examples":[{"language":"markdown","displayName":"docs/kittens.md","code":"# Kittens\n\nThe `kittens` module adopts, feeds, and pets kittens."}],"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```mjs 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    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\n`target`, `input` and `output` also have [CLI](./cli.html) flags, which win\nover the file. The [configuration reference](./configuration.html)\nlists every other option.","summary":"Create `doc-kit.config.mjs` next to your `package.json`:","examples":[{"language":"mjs","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    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/cli 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/cli 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/cli generate"},{"language":"bash","displayName":null,"code":"npx @doc-kit/cli 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":[]}]}