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.

## `kittens.adopt(name[, options])`

<!-- YAML
added: v1.0.0
-->

- `name` {string} The kitten's name.
- `options` {Object}
  - `color` {string} Coat color. **Default:** `'tabby'`.
- Returns: {Promise} Fulfills with the adopted kitten.

Adopts a kitten, once the paperwork is done.

It's regular Markdown, and reads as such on GitHub. doc-kit also reads the API in it: the heading is a method with its signature, the list holds its typed parameters, and the comment is its history. Writing documentation covers the rest.

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: {
    project: 'Kittens',
    version: '1.0.0',
    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.
• project and version go into page titles. Without them, doc-kit uses the name in your package.json and the version of Node.js running it.

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

npx doc-kit 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 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.