feat(docs): add documentation for doc-kit

[bmuenzenmeyer]

Description

Introduces the doc-kit documentation site, built with doc-kit!
This also serves as a reasonable simple web example.

Validation

npm run docs:build
npx serve www/out

Getting started suggestion end-state

Related Issues

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 18, 2026 6:46am

[codecov]

Codecov Report

❌ Patch coverage is 0% with 260 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.89%. Comparing base (d7bdf39) to head (fdc99ec).
⚠️ Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
www/theme/SideBar.jsx	0.00%	103 Missing ⚠️
scripts/build-docs-content.mjs	0.00%	82 Missing ⚠️
www/doc-kit.config.mjs	0.00%	75 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #889      +/-   ##
==========================================
- Coverage   85.04%   84.89%   -0.16%     
==========================================
  Files         179      191      +12     
  Lines       16496    17406     +910     
  Branches     1500     1540      +40     
==========================================
+ Hits        14029    14776     +747     
- Misses       2457     2623     +166     
+ Partials       10        7       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

web Generator

File	Base	Head	Diff
all.html	19.94 MB	19.94 MB	-234.00 B (-0.00%)

[AugustinMauroy]

Noice !

also we should add a "why doc-kit" section but with a "TBD" and in future have comparison with fuma-docs/docausorus ...

[AugustinMauroy]

what if we deploy the docs on GH page ?

[bmuenzenmeyer]

i dont have strong opinions here other that continuing our current patterns.

[cursor]

PR Summary

Low Risk
Changes are docs, build scripts, CI, and markdown heading tweaks; no runtime or security-sensitive pipeline logic is modified.

Overview
Adds a documentation site for doc-kit that is built with the project's own web and orama-db generators, serving as a live web target example.

Build pipeline: scripts/build-docs-content.mjs merges www/pages/*.md, docs/*.md, and each src/generators/*/README.md (as generator-*.md) into gitignored www/content/. npm run docs:build runs that script then doc-kit generate via www/doc-kit.config.mjs, outputting to www/out/. A GitHub Actions workflow builds on PR/push and uploads the docs-site artifact.

Site config & UX: www/doc-kit.config.mjs uses flat URLs, empty changelog/index, disables the synthetic Node.js index page, and wires a custom www/theme/SideBar.jsx (guide ordering, Pages vs Generators groups, inline-code labels). New narrative pages include www/pages/index.md and getting-started.md.

Supporting tweaks: Generator README headings are normalized for the site; docs/configuration.md shows target in the basic example; package.json gains docs:build and an explicit npm files list; Prettier ignores/prose-wrap for www/pages.

^{Reviewed by Cursor Bugbot for commit fdc99ec. Bugbot is set up for automated code reviews on this repo. Configure here.}

[avivkeller]

Would it be better to use a glob for this?

**/*.md?

[bmuenzenmeyer]

i dont have strong opinions either way, but knew that i

• wanted to clean out
• load very specific subset of three possible patterns, but perhaps not other future markdown.

[avivkeller]

What about something like?

import { glob, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { basename, dirname, join } from 'node:path';

const ROOT = join(import.meta.dirname, '..');
const CONTENT = join(ROOT, 'www', 'content');

const SOURCES = [
  { pattern: 'www/pages/*.md', rename: basename },
  { pattern: 'docs/*.md', rename: basename },
  {
    pattern: 'src/generators/*/README.md',
    rename: (file) => `generators/${basename(dirname(file))}.md`,
  },
];

/**
 * Collects the `{ name, markdown }` pages to write into `www/content/`.
 *
 * @returns {Promise<Array<{ name: string, markdown: string }>>}
 */
const collectPages = async () => {
  const groups = await Promise.all(
    SOURCES.map(async ({ pattern, rename }) => {
      const files = await Array.fromAsync(glob(pattern, { cwd: ROOT }));
      return Promise.all(
        files.sort().map(async (file) => ({
          name: rename(file),
          markdown: await readFile(join(ROOT, file), 'utf-8'),
        }))
      );
    })
  );
  return groups.flat();
};

const pages = await collectPages();

await rm(CONTENT, { recursive: true, force: true });
await mkdir(CONTENT, { recursive: true });
await Promise.all(
  pages.map(({ name, markdown }) => writeFile(join(CONTENT, name), markdown))
);
console.log(`Wrote ${pages.length} pages to www/content/`);

(Note I also moved generator- to generator/ in this example)

[avivkeller]

What does "no additional dependencies" mean? It depends on other generators (e.g. AST)

[bmuenzenmeyer]

to run in the browser. it's html

[avivkeller]

that's not very clear, imo

[avivkeller]

We can also leave this blank to remove the link entirely

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f035e7. Configure here.}

[AugustinMauroy]

missing link to orama docs

[bmuenzenmeyer]

a good follow up