@kirchdev/duxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Titus Kirch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/wordmark-dark.svg">
+  <img src=".github/assets/wordmark-light.svg" alt="duxt" width="200" />
+</picture>
+
+**Versioned, multi-repo documentation for Nuxt — one line to extend, no collection boilerplate**
+
+[![npm Version](https://img.shields.io/npm/v/@kirchdev/duxt.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/@kirchdev/duxt)
+[![Downloads](https://img.shields.io/npm/dm/@kirchdev/duxt.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/@kirchdev/duxt)
+[![Tests](https://img.shields.io/github/actions/workflow/status/kirchDev/duxt/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/kirchDev/duxt/actions/workflows/ci.yml)
+[![Node Version](https://img.shields.io/node/v/@kirchdev/duxt.svg?style=flat-square&color=8993be)](https://www.npmjs.com/package/@kirchdev/duxt)
+[![License: MIT](https://img.shields.io/npm/l/@kirchdev/duxt.svg?style=flat-square&color=10b981)](LICENSE)
+
+</div>
+
+---
+
+```ts
+export default defineNuxtConfig({
+  extends: ['@kirchdev/duxt'],
+})
+```
+
+That's it. Put your Markdown in `docs/` and you have a themed documentation site — search, navigation, table of contents, dark mode, `llms.txt` and an MCP server — with no collection, no layout and no config written by hand.
+
+## 🤔 Why
+
+Nuxt Content v3 already downloads and caches a git repository, at a branch or at a tag, private ones included — so nothing here rebuilds that. What it does not give you is the part that gets retyped in every documentation repo: one collection per version × repository, a URL scheme that carries them, a version switcher that knows which page exists where, and a theme on top.
+
+duxt turns all of it into one list. Sources are declared once, and the collections, the prefixes, the switcher, the redirects and the sitemap are generated from that declaration.
+
+## 📦 Install & run
+
+```bash
+pnpm add -D @kirchdev/duxt
+```
+
+The `extends` line above is the whole of the single-folder case. Everything beyond it is one file — `app/app.config.ts`, which both halves of the layer read:
+
+```ts
+export default defineAppConfig({
+  duxt: {
+    title: 'Acme',
+    sources: [
+      { path: 'docs', slug: 'acme' },                          // this repository
+      { repo: 'acme/api', path: 'docs', refs: ['main', 'v2.0.0', 'v1.4.0'] },
+    ],
+    sourceOptions: { defaultRef: 'v2.0.0' },
+  },
+})
+```
+
+Two repositories and three refs become five collections, the URL prefixes that serve them, and a version switcher — none of which you write.
+
+## ✨ Features
+
+- **📦 Extend, don't scaffold** — a Nuxt layer: 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 entry per source instead of one Content collection per version × repository.
+- **🧭 Version switcher and URL scheme** — `/[repo]/[version]/[...slug]`, collapsing cleanly when there is one source and no versions, with a lifecycle per version that decides the banner a reader gets.
+- **🌿 Git-native sourcing** — branches, tags, private repositories and hash-based caching come straight from Content v3's own `repository` support; `'latest'` resolves to the newest semver tag at build time.
+- **🤖 Machine-readable by default** — `llms.txt`, `llms-full.txt` and a real MCP server at `/mcp`, generated from the same collections the pages render from.
+- **🎨 shadcn-vue theme, owned not vendored** — Tailwind 4 with the components in `app/components/ui/`, MDC components in `app/components/content/`.
+- **🔍 Search, TOC, breadcrumb, prev/next** — ⌘K fuzzy search across every source, active-heading tracking, section landing pages, feedback and "Edit this page" links.
+- **🧯 A build that fails loudly** — a validator walks the parse cache for URL collisions, empty collections, broken links and missing titles, because every bug this layer actually had was a silent one.
+
+<details>
+<summary>Full feature list</summary>
+
+### Sources & versions
+
+- **🗂️ Sources as a list** — one compact entry per source instead of one Content collection per version × repository. The single unversioned folder 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 lifecycle per version (`upcoming`, `current`, `maintained`, `deprecated`, `eol`) that decides the banner a reader gets.
+- **🌿 Git-native sourcing** — branches, tags, private repositories and hash-based caching come straight from Content v3's own `repository` support; `'latest'` resolves to the newest semver tag at build time.
+- **🔁 Redirects from frontmatter** — `redirectFrom` on a moved page becomes route rules under every repository, version and locale prefix it is served at.
+
+### Theme & reading experience
+
+- **🎨 shadcn-vue theme, owned not vendored** — Tailwind 4 with the components in `app/components/ui/`, MDC components (`::callout`, `::steps`, `::code-group`, file trees, Mermaid) in `app/components/content/`.
+- **🔍 Search, TOC, breadcrumb, prev/next** — ⌘K fuzzy search across every source, active-heading tracking, section landing pages, feedback and "Edit this page" links.
+- **🌍 Seven locales out of the box** — `en-GB`, `en-US`, `de-DE`, `es-ES`, `fr-FR`, `pt-PT` and `pt-BR`; a site picks which of them it serves, and its own strings take a literal, a key or a per-locale record.
+
+### Machine-readable & SEO
+
+- **🤖 Machine-readable by default** — `llms.txt`, `llms-full.txt` and a real MCP server at `/mcp` (list pages, read a page, search), generated from the same collections the pages render from.
+- **📈 SEO and feeds included** — sitemap, robots, generated OG images, and an optional `/rss.xml` over a section you nominate.
+
+### Layer & build
+
+- **📦 Extend, don't scaffold** — a Nuxt layer: theme, pages, components and `app.config` defaults arrive with `extends` and are overridden file by file where you disagree.
+- **🧯 A build that fails loudly** — a validator walks the parse cache for URL collisions, empty collections, broken links and missing titles, because every bug this layer actually had was a silent one.
+- **🔎 DevTools tab** — the resolved sources, collections, prefixes, message catalogues and download cache, in dev, where guessing used to be the only option.
+
+</details>
+
+## ⚙️ Configuration
+
+Everything lives under the `duxt` key of `app.config.ts`. The keys most sites touch:
+
+| Key             | What it controls                                                          |
+| :-------------- | :------------------------------------------------------------------------ |
+| `sources`       | The documentation sources — folder, repository, refs, lifecycle, history. |
+| `sourceOptions` | How those become URL prefixes (`defaultRef`, `showRepo`, `showVersion`).  |
+| `title`         | The site name, in the navbar and every generated document.                |
+| `locales`       | Which of the layer's locales this site serves. Read at build time.        |
+
+Every text field takes a literal, an i18n key, or a per-locale record — a single-language site never sees the other two.
+
+> [!TIP]
+> The full surface — `navigation`, `sections`, `landing`, `feed`, `footer` and the rest — is typed, and the types are the documentation: [`app/types/duxt.d.ts`](app/types/duxt.d.ts) carries a comment per key explaining what it costs and when it is read.
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/kirchDev/duxt.git
+cd duxt
+pnpm install   # wires the husky hooks
+pnpm check     # lint + format + typecheck + tests + policy parity + build + a11y
+```
+
+The repo root **is** the layer — `nuxt.config.ts`, `content.config.ts`, `app/`, `modules/` and `server/` live there, and `package.json` points at them. `www/` beside it is the site that consumes the layer, and the development target: it deliberately carries the awkward cases — two repositories, four refs, one version of each lifecycle. It is not a template; the exemplary starting point lives in [`kirchDev/duxt-starter`](https://github.com/kirchDev/duxt-starter).
+
+## 🎨 Assets & branding
+
+The mark is the package name with its first letter bracketed — `[d]uxt` — because that is how the package is written where it is used: `extends: ['@kirchdev/duxt']`, an array with one entry. It is set in [IBM Plex Mono](https://github.com/IBM/plex) SemiBold and converted to outlines, so no asset depends on the font being installed anywhere.
+
+> [!NOTE]
+> The wordmark is **AI-assisted placeholder artwork** — a stand-in to be replaced at some point, with no fixed timeline. No image generator was involved: it is typeset, not drawn.
+
+Every asset, the colour values, why the icon's brackets are redrawn and the font licensing are in [Conventions → Branding](https://duxt.app/conventions/branding).
+
+> [!IMPORTANT]
+> The layer ships **no** branding. `duxt.logo` is unset by default, so `DuxtBrand` falls back to the consumer's own `duxt.title` beside a generic icon: a site extending duxt shows its own name in the header and footer and its own icon in the tab, never this one. These assets belong to this repository and to `www/`, not to the published package.
+
+## 🤝 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](CONTRIBUTING.md) for the full workflow.
+
+## 🛣️ Versioning
+
+[Semantic Versioning](https://semver.org/) via [release-please](https://github.com/googleapis/release-please) — see the [releases](https://github.com/kirchDev/duxt/releases).
+
+## 📄 License
+
+[MIT](LICENSE) © [Titus Kirch](https://github.com/TitusKirch/) / [IT-Dienstleistungen Titus Kirch](https://kirch.dev)

package/app/app.config.ts

@@ -0,0 +1,13 @@
+// The layer ships NO app.config values.
+//
+// Its defaults live in app/utils/duxt-config.ts, because Nuxt merges app.config
+// with defu and defu concatenates arrays — a consumer overriding `navigation`
+// would get the layer's entries appended to its own. `useDuxtConfig()` merges
+// them itself, replacing arrays rather than adding to them.
+//
+// The resolved source manifest used to be the one exception that had to sit
+// here. It no longer does: the duxt module resolves it from the site's own
+// `app.config.ts` and writes it back as `resolvedSources`.
+export default defineAppConfig({
+  duxt: {}
+});

package/app/app.vue

@@ -0,0 +1,122 @@
+<script setup lang="ts">
+/**
+ * The locale's head tags.
+ *
+ * `lang` and `dir` are set by hand rather than through `useLocaleHead`, because
+ * that composable warns ONCE PER RENDER when the site has no `baseUrl` — and it
+ * does so from `createHeadContext`, before it ever looks at whether alternate
+ * links were asked for. Passing `seo: false` does not quiet it; not calling it
+ * does.
+ *
+ * So the alternate links — the ones telling a search engine these pages are
+ * translations of one another rather than duplicates — are emitted only when
+ * the site knows its own origin. That is also the honest way round: a relative
+ * `hreflang` is not a valid one, and telling a crawler nothing beats telling it
+ * something untrue.
+ *
+ * Set `NUXT_PUBLIC_I18N_BASE_URL` in the deployment, or `i18n.baseUrl` in the
+ * consumer's config; duxt cannot guess it.
+ */
+const { locale, locales } = useI18n();
+const duxt = useDuxtConfig();
+
+const baseUrl = (useRuntimeConfig().public as { i18n?: { baseUrl?: string } })
+  .i18n?.baseUrl;
+
+const direction = computed(() => {
+  const current = locales.value.find(
+    (entry) => (typeof entry === 'string' ? entry : entry.code) === locale.value
+  );
+
+  return (typeof current === 'object' && current?.dir) || 'ltr';
+});
+
+useHead(() => ({
+  htmlAttrs: { lang: locale.value, dir: direction.value },
+
+  // Every page said only its own title, so a tab, a bookmark and a search
+  // result all read "Deploying" with nothing saying whose documentation it is.
+  // A page setting no title of its own gets the site name alone rather than a
+  // dangling separator.
+  titleTemplate: (title?: string) =>
+    title ? `${title} · ${duxt.title}` : duxt.title,
+
+  // A feed a reader's client can find without being told where it is. Only
+  // when there is one — see `duxt.feed`.
+  link: duxt.feed?.path
+    ? [
+        {
+          rel: 'alternate',
+          type: 'application/rss+xml',
+          title: duxt.feed.title ?? duxt.title,
+          href: '/rss.xml'
+        }
+      ]
+    : []
+}));
+
+if (baseUrl) {
+  const localeHead = useLocaleHead({ dir: false, lang: false, seo: true });
+  useHead(() => localeHead.value);
+}
+
+/**
+ * `og:locale`, which nuxt-seo-utils does not derive from i18n.
+ *
+ * Open Graph spells a locale with an underscore — `de_DE`, not `de-DE` — and
+ * the alternates are the OTHER locales this site serves, so a share card comes
+ * back in the reader's language where the network offers the choice. Only where
+ * the site has more than one; a single-locale site listing no alternates is
+ * correct, not incomplete.
+ */
+const ogLocale = (code: string) => code.replace('-', '_');
+
+useSeoMeta({
+  ogSiteName: () => duxt.title,
+  ogLocale: () => ogLocale(locale.value),
+  ogLocaleAlternate: () =>
+    locales.value
+      .map((entry) => (typeof entry === 'string' ? entry : entry.code))
+      .filter((code) => code !== locale.value)
+      .map(ogLocale)
+});
+
+/**
+ * WHAT THE SITE IS, once, for every page under it.
+ *
+ * nuxt-schema-org keeps one `@graph` per document and merges into it, so this
+ * node and the per-page `Article` in `[...slug].vue` end up in the same script
+ * tag with the references between them resolved — which is the whole reason the
+ * hand-written JSON-LD that used to live there could go.
+ *
+ * The `Organization` is conditional and stays that way: duxt renders somebody
+ * else's documentation and must not name a publisher it invented. A consumer
+ * fills in `duxt.organization`; until then the site describes itself and no
+ * more.
+ */
+useSchemaOrg([
+  defineWebSite({
+    name: duxt.title,
+    inLanguage: locale.value
+  }),
+  ...(duxt.organization?.name
+    ? [
+        defineOrganization({
+          name: duxt.organization.name,
+          url: duxt.organization.url,
+          logo: duxt.organization.logo
+        })
+      ]
+    : [])
+]);
+</script>
+
+<template>
+  <!-- Reads the new page's title into a live region after a client-side
+       navigation; the focus half of the same problem is useDuxtPageFocus. -->
+  <NuxtRouteAnnouncer />
+
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>