feat: localise the documentation and clear the layer of duxt's own content

.github/workflows/ci.yml

@@ -23,4 +23,4 @@ permissions:
 jobs:
   check:
     name: CI
-    uses: kirchDev/workflows/.github/workflows/_ci-check.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_ci-check.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2

.github/workflows/codeql.yml

@@ -28,4 +28,4 @@ jobs:
       packages: read
       actions: read
       contents: read
-    uses: kirchDev/workflows/.github/workflows/_codeql.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_codeql.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2

.github/workflows/fast-forward-queue.yml

@@ -34,7 +34,7 @@ jobs:
       pull-requests: read
       checks: read
       statuses: read
-    uses: kirchDev/workflows/.github/workflows/_fast-forward-queue.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_fast-forward-queue.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2
     with:
       pr: ${{ inputs.pr }}
     secrets:

.github/workflows/promotion-pr.yml

@@ -18,4 +18,4 @@ permissions:
 jobs:
   promotion-pr:
     name: Promotion PR
-    uses: kirchDev/workflows/.github/workflows/_promotion-pr.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_promotion-pr.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2

.github/workflows/queue-branch.yml

@@ -20,6 +20,6 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    uses: kirchDev/workflows/.github/workflows/_queue-branch.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_queue-branch.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2
     secrets:
       BWS_ACCESS_TOKEN: ${{ secrets.BWS_ACCESS_TOKEN }}

.github/workflows/release-please.yml

@@ -15,6 +15,6 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    uses: kirchDev/workflows/.github/workflows/_release-please.yml@94cbcbd676b989ac6c6327055a240132f5cd76a5 # v0.8.0
+    uses: kirchDev/workflows/.github/workflows/_release-please.yml@1e57db95ff601f03ae87b78e329ef238f9d0cbf6 # v0.8.2
     secrets:
       BWS_ACCESS_TOKEN: ${{ secrets.BWS_ACCESS_TOKEN }}

.gitignore

@@ -1,5 +1,5 @@
 # region gitignore-sync
-# stacks: core, agents, git, node, nuxt, vscode, intellij, macos, windows, linux
+# stacks: core, agents, git, node, nuxt, dotenv, vscode, intellij, macos, windows, linux
 # ─────────────────────────────────────────
 
 # region core@v1
@@ -43,6 +43,14 @@ coverage
 .data
 # endregion
 
+# region dotenv@v1
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.testing
+# endregion
+
 # region vscode@v1
 .vscode/*
 !.vscode/extensions.json

.oxfmtrc.json

@@ -13,6 +13,7 @@
     "CLAUDE.md",
     "AGENTS.md",
     "docs/**/*.md",
-    "www/content/**/*.md"
+    "www/content/**/*.md",
+    "public/devtools/*.html"
   ]
 }

.tituskirch-skills.json

@@ -48,7 +48,9 @@
     }
   },
   "docs": {
-    "preset": "package"
+    "preset": "package",
+    "render": "duxt",
+    "locales": ["de", "es", "fr", "pt"]
   },
   "work": {
     "tracker": "github",

README.md

@@ -1,6 +1,9 @@
 <div align="center">
 
-# 📚 duxt
+<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**
 
@@ -118,6 +121,18 @@ pnpm check     # lint + format + typecheck + tests + policy parity + build + a11
 
 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`.

app/app.vue

@@ -59,6 +59,56 @@ 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>

app/assets/css/duxt.css

@@ -15,78 +15,101 @@
    sets it with classSuffix: '' so the two agree. */
 @custom-variant dark (&:is(.dark *));
 
-/* The neutral base palette, in oklch. A consumer overrides a token by
-   redefining it in its own stylesheet — no fork of this file needed. */
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  /* shadcn's own value is oklch(0.556 0 0). Measured, that is 4.73:1 on the
-     page background — and 4.34:1 on --muted / --accent, which is where this
-     token actually lands: a hovered sidebar link, a badge, the sheet. So the
-     default fails AA on exactly the surfaces it is used on. 0.52 gives 5.51:1
-     and 5.05:1, and this token carries the page descriptions, the table of
-     contents and the breadcrumb — too much text to leave borderline. */
-  --muted-foreground: oklch(0.52 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  /* THE FOREGROUND FOLLOWS THE BACKGROUND'S LIGHTNESS, not the mode's. A pale
-     green with white on it reads as a badge and measures 3.12:1, which is a
-     badge nobody with low vision can read. Above roughly L 0.6 the pair takes
-     dark text, below it white — `--warning` already did, and success, info and
-     dark-mode destructive were simply missed. Enforced in
-     `tests/contrast.test.ts`; see the note on `--muted-foreground` above for
-     why the browser check cannot answer this. */
-  --success: oklch(0.63 0.17 149);
-  --success-foreground: oklch(0.145 0 0);
-  --warning: oklch(0.75 0.16 70);
-  --warning-foreground: oklch(0.145 0 0);
-  --info: oklch(0.62 0.16 244);
-  --info-foreground: oklch(0.145 0 0);
-}
+/*
+ * The neutral base palette, in oklch. A consumer overrides a token by
+ * redefining it in its own stylesheet — no fork of this file needed.
+ *
+ * IN A CASCADE LAYER, so that override cannot lose a race. Unlayered CSS beats
+ * layered CSS whatever the source order — and source order is not something
+ * this file controls. Vite resolves the stylesheet's absolute path along two
+ * routes at once, `/_nuxt/@fs/<abs>` and `/_nuxt/<abs>`, and deduplicates
+ * neither, so a second copy of this file lands AFTER the consumer's own `css`
+ * entry. At equal specificity the values below then won on order alone, and
+ * which one painted first came down to which 313 kB response arrived first: a
+ * consumer's buttons and badges flashed neutral before turning branded, and
+ * differently on every reload.
+ *
+ * The layer is ANONYMOUS on purpose. A named one can be reordered by a consumer
+ * writing `@layer` itself, which would hand the race straight back; an
+ * anonymous layer cannot be named again, so nothing downstream can move its own
+ * rules below these.
+ *
+ * Only the tokens go in here. Everything further down this file styles the
+ * layer's own components, where a consumer overriding by name is meant to need
+ * the specificity it already takes.
+ */
+@layer {
+  :root {
+    --radius: 0.625rem;
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+    --secondary: oklch(0.97 0 0);
+    --secondary-foreground: oklch(0.205 0 0);
+    --muted: oklch(0.97 0 0);
+    /* shadcn's own value is oklch(0.556 0 0). Measured, that is 4.73:1 on the
+       page background — and 4.34:1 on --muted / --accent, which is where this
+       token actually lands: a hovered sidebar link, a badge, the sheet. So the
+       default fails AA on exactly the surfaces it is used on. 0.52 gives 5.51:1
+       and 5.05:1, and this token carries the page descriptions, the table of
+       contents and the breadcrumb — too much text to leave borderline. */
+    --muted-foreground: oklch(0.52 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --destructive-foreground: oklch(0.985 0 0);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    /* THE FOREGROUND FOLLOWS THE BACKGROUND'S LIGHTNESS, not the mode's. A pale
+       green with white on it reads as a badge and measures 3.12:1, which is a
+       badge nobody with low vision can read. Above roughly L 0.6 the pair takes
+       dark text, below it white — `--warning` already did, and success, info and
+       dark-mode destructive were simply missed. Enforced in
+       `tests/contrast.test.ts`; see the note on `--muted-foreground` above for
+       why the browser check cannot answer this. */
+    --success: oklch(0.63 0.17 149);
+    --success-foreground: oklch(0.145 0 0);
+    --warning: oklch(0.75 0.16 70);
+    --warning-foreground: oklch(0.145 0 0);
+    --info: oklch(0.62 0.16 244);
+    --info-foreground: oklch(0.145 0 0);
+  }
 
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.922 0 0);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  /* Same measurement in the dark: 7.63:1 on the background but 5.83:1 on
-     --muted. Lifted for the same reason, by less, because it starts higher. */
-  --muted-foreground: oklch(0.72 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --destructive-foreground: oklch(0.145 0 0);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
-  --success: oklch(0.7 0.16 149);
-  --success-foreground: oklch(0.145 0 0);
-  --warning: oklch(0.8 0.15 70);
-  --warning-foreground: oklch(0.145 0 0);
-  --info: oklch(0.7 0.14 244);
-  --info-foreground: oklch(0.145 0 0);
+  .dark {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.922 0 0);
+    --primary-foreground: oklch(0.205 0 0);
+    --secondary: oklch(0.269 0 0);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    /* Same measurement in the dark: 7.63:1 on the background but 5.83:1 on
+       --muted. Lifted for the same reason, by less, because it starts higher. */
+    --muted-foreground: oklch(0.72 0 0);
+    --accent: oklch(0.269 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --destructive-foreground: oklch(0.145 0 0);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --success: oklch(0.7 0.16 149);
+    --success-foreground: oklch(0.145 0 0);
+    --warning: oklch(0.8 0.15 70);
+    --warning-foreground: oklch(0.145 0 0);
+    --info: oklch(0.7 0.14 244);
+    --info-foreground: oklch(0.145 0 0);
+  }
 }
 
 @theme inline {
@@ -192,12 +215,25 @@
    surfaces, and in dark mode the inner one reads as a highlighted row. Not
    scoped to .typeset, because the package-manager block renders the same
    markup outside a rendered page. */
+/* The heading link wraps the words, so it has to shed what `typeset` gives
+   every other link — the underline would draw a rule under every H2 on the
+   site. `relative` is what the marker below positions against: anchored to the
+   text rather than to the heading box, it lands the same distance out whatever
+   the heading's own margins are. */
+.typeset :where(.duxt-heading-link) {
+  @apply relative no-underline;
+  text-decoration-line: none;
+}
+
 .typeset :where(.duxt-anchor) {
-  @apply absolute -left-5 font-normal text-muted-foreground no-underline opacity-0 transition-opacity;
+  @apply absolute -left-5 font-normal text-muted-foreground opacity-0 transition-opacity;
 }
 
+/* Revealed by hovering the heading, not the marker: the marker is 1.25rem
+   outside the text and nobody hunts for it. Focus does the same for the
+   keyboard, where the link is reached without a pointer at all. */
 .typeset :where(h2:hover, h3:hover, h4:hover) .duxt-anchor,
-.typeset :where(.duxt-anchor:focus-visible) {
+.typeset :where(.duxt-heading-link:focus-visible) .duxt-anchor {
   @apply opacity-100;
 }