Getting started

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.

Install the CLI, and the generators that build the site:

npm install --save-dev @doc-kit/cli @doc-kit/generator-react

@doc-kit/cli gives you the doc-kit command and the core generators, such as json. @doc-kit/generator-react adds the website and what comes with it: the search index, llms.txt and a sitemap.

Create docs/kittens.md:

# Kittens

The `kittens` module adopts, feeds, and pets kittens.

Writing documentation shows how to document an API in it.

Create doc-kit.config.mjs next to your package.json:

/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */
export default {
  target: ['html', 'orama-db'],

  global: {
    input: ['docs/**/*.md'],
    output: 'out',
  },
};

• target lists the generators to run: html builds the site, and orama-db its search index.
• input takes glob patterns, and output is the directory to write to.

target, input and output also have CLI flags, which win over the file. The configuration reference lists every other option.

npx @doc-kit/cli generate

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:

npx @doc-kit/cli preview

Then open http://localhost:3000/kittens.html. preview serves what generate built; pass it any generate option, such as --config-file doc-kit.config.mjs, and it builds first. Any other static server works too, such as npx serve out.

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:

import { join } from 'node:path';

/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */
export default {
  // target and global as above

  html: {
    // Your component in place of the project's name
    imports: {
      '#theme/Logo': join(import.meta.dirname, 'theme/Logo.jsx'),
    },

    // Bundled after doc-kit's own styles, so your rules win
    stylesheets: [join(import.meta.dirname, 'theme/styles.css')],
  },
};

export default () => <strong>Kittens</strong>;

:root {
  --color-brand-100: #f7f1fb;
  --color-brand-200: #ead9fb;
  --color-brand-300: #dbbdf9;
  --color-brand-400: #c79bf2;
  --color-brand-500: #b07ae6;
  --color-brand-600: #9756d6;
  --color-brand-700: #7d3cbe;
  --color-brand-800: #642b9e;
  --color-brand-900: #361b52;
}

Customizing the site covers the other parts of the page you can replace, and the Website generator lists every option.

• Writing documentation: the conventions that turn Markdown into an API reference.
• Customizing the site: navigation, components, MDX and the bundler.
• Generators: JSON, llms.txt, a sitemap, and every other output doc-kit can build.
• Publishing your docs: hosting, caching and base URLs.
• Creating generators: outputs of your own.