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 7:14pm

[codecov]

Codecov Report

❌ Patch coverage is 20.32787% with 243 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.06%. Comparing base (d7bdf39) to head (358158f).
⚠️ Report is 14 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #889      +/-   ##
==========================================
+ Coverage   85.04%   85.06%   +0.02%     
==========================================
  Files         179      192      +13     
  Lines       16496    17450     +954     
  Branches     1500     1550      +50     
==========================================
+ Hits        14029    14844     +815     
- Misses       2457     2600     +143     
+ Partials       10        6       -4     

☔ 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 ...

[cursor]

PR Summary

Low Risk
Mostly docs-site and CI additions; the relative() change is localized, tested, and only affects internal link resolution for nested paths.

Overview
Adds a self-hosted doc-kit documentation site under www/: narrative pages, a content-assembly script that merges www/pages, docs/, and generator READMEs into gitignored www/content/, www/doc-kit.config.mjs for web + orama-db, a custom sidebar theme, and npm run docs:build plus a GitHub Actions workflow that builds and uploads www/out.

Fixes relative() in src/utils/url.mjs so the target path’s last segment is not stripped during common-prefix matching—e.g. linking to /generators from /generators/web now yields ../generators instead of ., with new unit tests. This matters for nested doc trees (including the new site’s generators/* pages).

Smaller follow-ons: publish files whitelist in package.json, Prettier prose wrap for www/pages, configuration doc example with target, and generator README heading demotion (## → #) for consistent site rendering.

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

[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.}

[bmuenzenmeyer]

I spent a lot of time sort of incredulous that Claude suggested there was a nascent bug in doc-kit that our beta, or learn, or webpack had yet to find. So perhaps @avivkeller another pass at d3f2819

[avivkeller]

I think what Claude is getting at is that if I navigate from parent/child to parent/, our relative() helper will generate .. instead of ../parent.

That said, this isn't really a doc-kit issue, rather, it's a consequence of how browsers resolve relative URLs. Redirecting from a URL with a trailing slash behaves differently than redirecting from one without. Claude's change fixes the parent/child -> parent case, but it breaks parent/child/ -> parent, which was previously supported (I think, I'm eyeballing this). As far as I can tell, it's an either-or tradeoff: we either assume trailing slashes or we don't.

In practice, this only becomes an issue if all of the following are true:

1. You're using nested directories with doc-kit.
2. You've configured doc-kit to use relative links instead of absolute links.

We intentionally don't enable relative links on our Learn sites, webpack sites, or our main docs site because they can produce obscure, and often incorrect, URLs for exactly this reason.

[bmuenzenmeyer]

i purposely made it atomic so it could be reverted, if we so choose.
edit: actually this is a dumb statement, supposedly doc-kit docs links wont render correctly without it. need to try

[avivkeller]

@bmuenzenmeyer merge when ready