docuconf.dev
The website for docuconf: typed environment contracts for every language, validated by your Kubernetes platform before anything deploys.
Built with Next.js (App Router, static export), Tailwind CSS and MDX, with Pagefind search.
npm ci
npm run dev # http://localhost:3000 (search works only in the built site)
npm run build # static site in out/, then the search index in out/pagefind/
npm run check:content # pages name SDKs only through sdk-data.ts
- The landing page is
src/app/page.tsx.
- Each project page is an MDX file in
src/app/(docs)/<slug>/page.mdx. To add one, create the file and list it in NAV_GROUPS in src/components/site.tsx.
- Code is highlighted at build time with Shiki, in light and dark themes that follow the reader's OS setting. Every code block has a copy button; language tabs remember the reader's choice and link with
?lang=.
SDKs and their snippets
src/lib/sdk-data.ts is the only place that knows about the SDKs. The homepage, the
/languages/<slug>/ Get started pages, /examples/, the SDK requirements matrix, the roadmap, llms.txt and the
JSON-LD all read it, and npm run check:content fails if a page lists languages by hand.
Every code snippet those pages show lives in snippets/<slug>/:
| Path | What it is |
|---|
sdk/... | Copies of files from the SDK repository (the orders example), at the same paths. CI fails if they differ. |
overlay/... | Files the site adds to the SDK checkout: the tests the Test step shows, a values file for docuconf vet. |
install/ | A small project that installs the SDK exactly as the Install step says. |
out/<check>.txt | The output a check must print, which the page shows. ... skips lines; … matches any text. |
The commands come from each row's checks, and the pages show the same strings.
scripts/snippets.ts runs them, and the snippets workflow runs it for every SDK against
that repository's main branch, in the SDK's own toolchain image, on every push and daily.
# Check one SDK against a local clone's origin/main (a copy; the clone is not touched):
node scripts/snippets.ts check python --git ../docuconf-python --ref origin/main
# After an SDK changes: refresh the copies and expected output, then review the diff.
node scripts/snippets.ts check python --git ../docuconf-python --ref origin/main --update
--git copies the clone with git archive, which leaves out paths marked export-ignore: docuconf-php's examples are, so check laravel and symfony with --sdk on a worktree of that clone instead (--sdk runs in place). Locally, the commands use the toolchains on your PATH; SNIPPETS_SHELL can name a wrapper that runs them
elsewhere (it is called with the directory and the command).
Adding a language
- Add a row to
SDK_ROWS in src/lib/sdk-data.ts: the matrix facts, the Get started prose (guide), the toolchain
image (ci) and the commands (checks).
- Create
snippets/<slug>/: copy the example's declaration and contract.cue into sdk/, write the test in
overlay/ and the install project in install/.
- Run
node scripts/snippets.ts check <slug> --git <clone> --update to record the outputs, then npm run build.
No page or component changes: the new language appears everywhere, and CI starts checking it.
Deploy
.github/workflows/deploy.yml checks types and content and builds every pull request, and deploys main to GitHub Pages. In the repository settings, set Pages → Source to "GitHub Actions".
