📚 duxt

An idea: versioned, multi-repo documentation for Nuxt — one line to extend, no collection boilerplate

---

export default defineNuxtConfig({
  extends: ['@kirchdev/duxt'],
})

The idea is that this line is the whole setup: Nuxt Content v3 underneath, a theme on top, and — when you need them — several source repositories and several versions of the docs, declared as a list rather than as one collection per version × repo.

Important

This is a sketch, not a product. Nothing is built, nothing is published to npm, and none of the design below is decided — including whether the layer gets built on a clean base or on top of Docus / Nuxt UI, and whether it stays public at all. Everything here reads as a proposal to argue with.

✨ The idea

• 📦 Extend, don't scaffold — a Nuxt layer, so the theme, pages, components and app.config defaults arrive with extends and are overridden file by file where you disagree.

• 🗂️ Sources as a list — one compact declaration per source instead of one Content collection per version × repo:

  sources: [
    { path: 'docs' },                                 // this repo, current branch
    { path: 'docs', refs: ['v1.x', 'v2.x', 'main'] }, // versioned
    { repo: 'kirchDev/app', path: 'docs' },           // another repo
  ]

  The single-source, unversioned case is the default and needs no config at all.

• 🔀 Version switcher and URL scheme — /[repo]/[version]/[...slug], collapsing cleanly when there is one source and no versions, with a defined fallback for a page that a given version does not have.

• 🌿 Git-native sourcing — branches, tags, private repositories and hash-based caching come straight from Nuxt Content v3's own repository support. duxt adds the ergonomics on top, not a second mechanism.

• 🤖 Machine-readable output — llms.txt and an MCP route over the same content, generated at build time.

🚀 Setup (intended)

pnpm add -D @kirchdev/duxt

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@kirchdev/duxt'],
})

Put your Markdown in docs/ and start the app. Everything beyond that — more sources, versions, theme overrides — would be opt-in.

Neither the package nor kirchDev/duxt-starter exists yet; the starter, if it happens, would be cloned with npx nuxi@latest init -t github:kirchDev/duxt-starter.

🧪 Development

git clone https://github.com/kirchDev/duxt.git
cd duxt
pnpm install   # wires the husky hooks
pnpm check     # lint + format + typecheck + policy parity

playground/ does not exist yet. It is meant to be where the layer is developed — it deliberately carries edge cases, ugly frontmatter, several sources and a tag to read from. It is not a template; the exemplary starting point lives in kirchDev/duxt-starter.

🤝 Contributing

PRs welcome. Conventional Commits are enforced via commitlint, and husky runs the linters on git commit. Branch off dev.

Tip

Run pnpm check:fix before pushing — CI will catch what husky missed.

See CONTRIBUTING.md for the full workflow.

🛣️ Versioning

Semantic Versioning via release-please — see the releases.

📄 License

MIT © Titus Kirch / IT-Dienstleistungen Titus Kirch