@kirchdev/duxt 0.1.1-dev-main.12-4d33ebf → 0.1.1-dev-main.30-1e18e2e

package/app/assets/css/duxt.css

@@ -331,10 +331,12 @@ details[open] > .duxt-schema-row .duxt-schema-tile .duxt-schema-minus {
    set at 0.6875rem in `muted-foreground`: the same idea, two sizes, two
    weights, two colours, on pages a reader moves between.
    
-   The colour is the DEFAULT and not the rule: a caller that has a tone of its
-   own — a changelog group — sets it after this class and wins. */
-.duxt-label {
-  @apply text-[0.6875rem] font-semibold tracking-[0.12em] text-muted-foreground uppercase;
+   Keep the defaults in the components layer so a caller's colour utilities
+   can override them. Unlayered rules beat utilities regardless of class order. */
+@layer components {
+  .duxt-label {
+    @apply text-[0.6875rem] font-semibold tracking-[0.12em] text-muted-foreground uppercase;
+  }
 }
 
 /* A release group's ENTRIES, which arrive as ordinary Markdown in

package/app/components/DuxtHeader.vue

@@ -6,6 +6,14 @@ const localeLink = useDuxtLink();
 
 const { data: navigation } = await useDuxtNavigation();
 
+// Nitro's HTML crawler treats v0.1.0 as a file with extension .0 and skips it.
+// Register known pages explicitly so their HTML and Nuxt payloads are emitted.
+if (import.meta.prerender) {
+  prerenderRoutes(
+    navigationPagePaths(navigation.value ?? []).map((path) => localeLink(path)!)
+  );
+}
+
 // The mobile sheet shows the same branch the sidebar does.
 const { items } = useDuxtSection(navigation);
 
@@ -148,7 +156,14 @@ function current(to?: string) {
           <UiSheetContent side="left" class="flex w-80 flex-col gap-0 p-0">
             <UiSheetHeader class="border-b pr-14">
               <UiSheetTitle class="flex items-center gap-2">
-                <DuxtBrand />
+                <NuxtLink
+                  :to="localeLink('/')"
+                  :aria-label="duxt.logo?.alt || duxt.title"
+                  class="flex items-center gap-2"
+                  @click="sheetOpen = false"
+                >
+                  <DuxtBrand />
+                </NuxtLink>
 
                 <!-- One version and no choice: a fact about the project, so it
                      sits with the identity as a badge rather than filling a
@@ -320,7 +335,7 @@ function current(to?: string) {
                 </ul>
               </template>
 
-              <template v-if="items.length">
+              <template v-if="path !== '/' && items.length">
                 <p
                   class="mt-6 mb-2 border-t px-2 pt-4 text-[11px] font-semibold tracking-wider text-muted-foreground uppercase first:mt-0 first:border-t-0 first:pt-0"
                 >

package/app/components/DuxtLandingProse.vue

@@ -42,8 +42,7 @@ const localeLink = useDuxtLink();
     <component
       :is="`h${level}`"
       :id="headingId"
-      class="font-semibold tracking-tight text-balance"
-      :class="level === 2 ? 'text-2xl sm:text-3xl' : 'text-xl sm:text-2xl'"
+      class="text-2xl font-semibold tracking-tight text-balance sm:text-3xl"
     >
       {{ prose.title }}
     </component>

package/app/components/DuxtOpenApiClient.vue

@@ -1161,7 +1161,7 @@ function pretty(text: string): string {
       <div
         :class="
           split
-            ? ['self-start', reverse ? 'lg:order-2' : 'lg:order-1']
+            ? ['min-w-0 self-start', reverse ? 'lg:order-2' : 'lg:order-1']
             : 'border-t px-4 py-3'
         "
       >
@@ -1199,14 +1199,14 @@ function pretty(text: string): string {
                 class="flex min-h-11 items-center gap-1 border-b bg-muted/40 px-2 py-1.5"
               >
                 <TabsList
-                  class="flex items-center gap-1"
+                  class="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto"
                   :aria-label="$t('duxt.openapi.client.samples') as string"
                 >
                   <TabsTrigger
                     v-for="entry in groups"
                     :key="entry"
                     :value="entry"
-                    class="flex cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1 font-mono text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm"
+                    class="flex shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1 font-mono text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm"
                   >
                     <Icon :name="groupIcon(entry)" class="size-3.5" />
                     {{ entry }}

package/app/components/DuxtVersion.vue

@@ -24,6 +24,7 @@ const props = withDefaults(defineProps<{ variant?: 'badge' | 'block' }>(), {
 const duxt = useDuxtConfig();
 const path = useDuxtPath();
 const localeLink = useDuxtLink();
+const { collection, source } = useDuxtCollection();
 
 /**
  * Versions come from the resolved source manifest, so the control can only
@@ -34,6 +35,31 @@ const localeLink = useDuxtLink();
  */
 const { choices: versions } = useDuxtVersion();
 
+/**
+ * A changelog is one global history, so it deliberately has no version
+ * selector. Its current release is still useful context, though: read the
+ * latest one from the overview's generated frontmatter instead of falling
+ * back to the site's package version. The parser writes that value while
+ * turning the changelog into the overview and release pages.
+ */
+const changelog = computed(
+  () =>
+    source.value?.generated?.type === 'changelog' &&
+    source.value.generated.versioning === 'global'
+);
+
+const { data: changelogPage } = await useAsyncData(
+  () => `duxt-changelog-version-${collection.value}-${path.value}`,
+  async () => {
+    if (!changelog.value) return undefined;
+
+    return (await queryCollection(collection.value as DuxtCollectionArg)
+      .path(path.value)
+      .first()) as { release?: string } | null;
+  },
+  { watch: [collection, path, changelog] }
+);
+
 const current = computed(() =>
   sourceForPath(
     path.value,
@@ -41,6 +67,10 @@ const current = computed(() =>
   )
 );
 
+const label = computed(
+  () => changelogPage.value?.release ?? current.value?.label ?? duxt.version
+);
+
 const { t, te } = useI18n();
 
 /**
@@ -94,7 +124,7 @@ function pathIn(version: { to?: string }) {
 
         <span class="grid min-w-0 flex-1 leading-tight">
           <span class="truncate font-mono text-sm font-medium">
-            {{ current?.label ?? duxt.version }}
+            {{ label }}
           </span>
           <span class="truncate text-xs text-muted-foreground">
             {{ (current && caption(current)) ?? $t('duxt.version.label') }}
@@ -112,7 +142,7 @@ function pathIn(version: { to?: string }) {
           variant="secondary"
           class="gap-1 font-mono text-[10px] hover:bg-accent"
         >
-          {{ current?.label ?? duxt.version }}
+          {{ label }}
           <Icon name="lucide:chevron-down" class="size-3 opacity-60" />
         </UiBadge>
       </button>
@@ -163,6 +193,6 @@ function pathIn(version: { to?: string }) {
     variant="secondary"
     class="font-mono text-[10px]"
   >
-    {{ duxt.version }}
+    {{ label }}
   </UiBadge>
 </template>

package/app/components/content/ProseA.vue

@@ -11,8 +11,9 @@
  * mid-sentence.
  *
  * So an absolute internal path is read as relative TO ITS OWN SOURCE, and the
- * prefix is put back here. A path that already carries the prefix is left
- * alone, so a link written the long way round still works.
+ * prefix is put back here. `~/` is the explicit website-root escape hatch for
+ * a link that has to leave that source. A path that already carries the prefix
+ * is left alone, so a link written the long way round still works.
  */
 const props = defineProps<{
   href?: string;
@@ -26,22 +27,26 @@ const external = computed(() =>
   Boolean(props.href && /^(?:[a-z]+:|\/\/)/i.test(props.href))
 );
 
+const internal = computed(() =>
+  Boolean(props.href?.startsWith('/') || props.href?.startsWith('~/'))
+);
+
 const to = computed(() => {
   const href = props.href ?? '';
-  if (external.value || !href.startsWith('/')) return href;
+  if (external.value || !internal.value) return href;
 
   const prefix = source.value?.prefix ?? '';
-  const [path, hash] = href.split('#');
-  const resolved =
-    prefix && !isInside(path!, prefix) ? `${prefix}${path}` : path!;
+  const [pathAndQuery, hash] = href.split('#');
+  const [path, query] = pathAndQuery!.split('?');
+  const resolved = resolveDocumentationPath(path!, prefix);
 
-  return `${localeLink(resolved)}${hash ? `#${hash}` : ''}`;
+  return `${localeLink(resolved)}${query ? `?${query}` : ''}${hash ? `#${hash}` : ''}`;
 });
 </script>
 
 <template>
   <a
-    v-if="external || !href?.startsWith('/')"
+    v-if="external || !internal"
     :href="href"
     :target="target ?? (external ? '_blank' : undefined)"
     :rel="external ? 'noopener' : undefined"

package/app/composables/useDuxtSearch.ts

@@ -1,3 +1,5 @@
+import type { DuxtResolvedSource } from '../../sources-resolve';
+import { searchSources } from '../utils/search-scope';
 import type { DuxtSearchSection } from '@duxt/composables/useFuzzySearch';
 
 /** A hit, with the source it came out of. */
@@ -22,18 +24,19 @@ export interface DuxtSearchHit extends DuxtSearchSection {
  * The source being read goes first in each round, because a reader searching
  * inside a project usually means that project.
  *
- * ONE VERSION PER REPOSITORY. Searching every version returns each page as many
+ * ONE VERSION PER ARTEFACT. Searching every version returns each page as many
  * times as there are versions, which buries the answer under its own history.
- * So each repository contributes the version the reader is in, or its default.
+ * Each docs tree and generated declaration contributes its current or default edition.
  */
 export function useDuxtSearch() {
   const duxt = useDuxtConfig();
   const { source } = useDuxtCollection();
+  const { locale, fallbackLocale } = useI18n();
 
   const sources = computed(() => duxt.resolvedSources ?? []);
 
   /**
-   * The collections to search, one per repository.
+   * The available collections; only selected editions are initialized.
    *
    * Fixed at setup, deliberately: each one needs its own `useSearchCollection`,
    * and a composable list that grows with the route is not a thing. The
@@ -79,38 +82,54 @@ export function useDuxtSearch() {
     }).search
   }));
 
-  /** One entry per repository: the version being read, else that repo's default. */
-  const active = computed(() => {
-    const current = source.value;
-    const byRepo = new Map<string, (typeof searchable)[number]>();
-
-    for (const entry of searchable) {
-      const key = entry.repo ?? '';
-      const chosen = byRepo.get(key);
-
-      if (entry.collection === current?.collection) {
-        byRepo.set(key, entry);
-        continue;
-      }
-
-      if (chosen?.collection === current?.collection) continue;
-      if (!chosen || (entry.isDefault && !chosen.isDefault)) {
-        byRepo.set(key, entry);
-      }
+  /** Selected editions, ordered by artefact and then preferred language. */
+  const active = computed(() =>
+    searchSources(
+      searchable,
+      source.value,
+      locale.value,
+      fallbackLocale.value as string | string[] | undefined
+    )
+  );
+
+  const pagePaths = new Map<string, Promise<Set<string>>>();
+  function paths(collection: string) {
+    let pending = pagePaths.get(collection);
+    if (!pending) {
+      pending = queryCollection(collection as DuxtCollectionArg)
+        .select('path')
+        .all()
+        .then((pages) => new Set(pages.map((page) => page.path)))
+        .catch((error) => {
+          pagePaths.delete(collection);
+          throw error;
+        });
+      pagePaths.set(collection, pending);
     }
+    return pending;
+  }
 
-    // The source being read leads; the rest keep the config's own order.
-    return [...byRepo.values()].sort((a, b) =>
-      a.collection === current?.collection
-        ? -1
-        : b.collection === current?.collection
-          ? 1
-          : 0
+  // A fallback may answer only for a PAGE absent from every better language,
+  // even when a heading or the search term exists only in the original.
+  async function visiblePages(wanted: DuxtResolvedSource[]) {
+    return Promise.all(
+      wanted.map(async (entry, index) => {
+        const preferred = wanted
+          .slice(0, index)
+          .filter((other) => other.prefix === entry.prefix);
+        return new Set(
+          (
+            await Promise.all(preferred.map((other) => paths(other.collection)))
+          ).flatMap((pages) => [...pages])
+        );
+      })
     );
-  });
+  }
 
   /** Only worth a badge when there is more than one thing to tell apart. */
-  const labelled = computed(() => active.value.length > 1);
+  const labelled = computed(
+    () => new Set(active.value.map((entry) => entry.prefix)).size > 1
+  );
 
   const labelOf = (entry: (typeof searchable)[number]) =>
     [entry.repo, entry.version].filter(Boolean).join(' ') ||
@@ -119,8 +138,8 @@ export function useDuxtSearch() {
 
   async function init() {
     await Promise.all(
-      searches
-        .filter((search) => active.value.includes(search.entry))
+      active.value
+        .map((entry) => searches.find((search) => search.entry === entry)!)
         .filter((search) => search.status.value === 'idle')
         .map((search) => search.init())
     );
@@ -153,17 +172,41 @@ export function useDuxtSearch() {
     term: string,
     limit = 20
   ): Promise<{ hits: DuxtSearchHit[]; approximate: boolean }> {
-    if (!term.trim()) return { hits: [], approximate: false };
+    if (!term.trim() || limit <= 0) return { hits: [], approximate: false };
 
     const wanted = active.value;
+    const hidden = await visiblePages(wanted);
+    async function visible(
+      query: (requested: number) => Promise<DuxtSearchSection[]>,
+      index: number
+    ) {
+      let requested = limit;
+      while (true) {
+        const hits = await query(requested);
+        const shown = hits.filter(
+          (hit) => !hidden[index]!.has(hit.id.split('#')[0]!)
+        );
+        if (
+          shown.length >= limit ||
+          hits.length < requested ||
+          !hidden[index]!.size
+        )
+          return shown.slice(0, limit);
+        requested *= 2;
+      }
+    }
 
     const lists = await Promise.all(
-      searches
-        .filter((entry) => wanted.includes(entry.entry))
-        .map(async (entry) => {
-          const hits = (await entry.search(term, {
-            limit
-          })) as DuxtSearchSection[];
+      wanted
+        .map((source) => searches.find((entry) => entry.entry === source)!)
+        .map(async (entry, index) => {
+          const hits = await visible(
+            async (requested) =>
+              (await entry.search(term, {
+                limit: requested
+              })) as DuxtSearchSection[],
+            index
+          );
 
           return hits.map((hit) => ({
             ...hit,
@@ -184,10 +227,13 @@ export function useDuxtSearch() {
     // leaves the reader with an empty box. Fuse gets a second look, over the
     // same sources and merged the same way.
     const fuzzy = await Promise.all(
-      approximate
-        .filter((entry) => wanted.includes(entry.entry))
-        .map(async (entry) => {
-          const hits = await entry.search(term, limit);
+      wanted
+        .map((source) => approximate.find((entry) => entry.entry === source)!)
+        .map(async (entry, index) => {
+          const hits = await visible(
+            (requested) => entry.search(term, requested),
+            index
+          );
 
           return hits.map((hit) => ({
             ...hit,

package/app/types/duxt.d.ts

@@ -185,6 +185,13 @@ declare global {
   interface DuxtSourceInput {
     /** Folder holding the Markdown, relative to the repository root. */
     path?: string;
+    /**
+     * Whether this source's Markdown is published as documentation pages.
+     *
+     * Set `false` for a source that only provides generated sections. It can
+     * then share the default URL prefix of a versioned documentation source.
+     */
+    content?: boolean;
     /** `owner/name` or a full git URL. Omitted means this repository. */
     repo?: string;
     /** Refs to publish as versions. Omitted means the current checkout. */

package/app/utils/documentation-link.ts

@@ -0,0 +1,14 @@
+import { isInside } from './version-paths';
+
+/**
+ * Resolve a documentation path as the reader will see it.
+ *
+ * Markdown paths normally belong to the source that contains them. `~/` is the
+ * explicit escape hatch: it starts at the website root so one source can name
+ * a page served by another source without hard-coding its own prefix.
+ */
+export function resolveDocumentationPath(path: string, prefix: string): string {
+  if (path.startsWith('~/')) return path.slice(1);
+
+  return prefix && !isInside(path, prefix) ? `${prefix}${path}` : path;
+}

package/app/utils/locale-path.ts

@@ -15,7 +15,10 @@ export function stripLocalePrefix(
   path: string,
   codes: Iterable<string>
 ): string {
-  return splitLocalePath(path, codes).path;
+  const documentPath = splitLocalePath(path, codes).path;
+  // Static hosts may append a slash; Content paths and prerendered async-data
+  // keys do not. Both URLs must reuse the same data during hydration.
+  return documentPath.replace(/\/+$/, '') || (documentPath ? '/' : '');
 }
 
 /**

package/app/utils/navigation-tree.ts

@@ -1,5 +1,18 @@
 import type { ContentNavigationItem } from '@nuxt/content';
 
+/** Actual pages, including dotted version paths; folder wrappers are not pages. */
+export function navigationPagePaths(items: ContentNavigationItem[]): string[] {
+  const paths = new Set<string>();
+  for (const item of items) {
+    if (item.children?.length) {
+      for (const path of navigationPagePaths(item.children)) paths.add(path);
+    } else {
+      paths.add(item.path);
+    }
+  }
+  return [...paths];
+}
+
 /** Find a node by path, anywhere in the tree. */
 export function findByPath(
   items: ContentNavigationItem[],

package/app/utils/search-scope.ts

@@ -0,0 +1,41 @@
+import {
+  sourcesForRoute,
+  type DuxtResolvedSource
+} from '../../sources-resolve';
+
+/** Select the editions participating in site-wide search. */
+export function searchSources(
+  sources: DuxtResolvedSource[],
+  current: DuxtResolvedSource | undefined,
+  locale?: string,
+  fallbackLocale?: string | string[]
+): DuxtResolvedSource[] {
+  const byArtefact = new Map<string, DuxtResolvedSource>();
+  for (const entry of sources) {
+    const key = JSON.stringify([entry.repo, entry.generated?.declaration]);
+    const chosen = byArtefact.get(key);
+    if (entry.collection === current?.collection) {
+      byArtefact.set(key, entry);
+      continue;
+    }
+    if (chosen?.collection === current?.collection) continue;
+    if (!chosen || (entry.isDefault && !chosen.isDefault))
+      byArtefact.set(key, entry);
+  }
+  return [...byArtefact.values()]
+    .sort((a, b) =>
+      a.collection === current?.collection
+        ? -1
+        : b.collection === current?.collection
+          ? 1
+          : 0
+    )
+    .flatMap((edition) =>
+      sourcesForRoute(
+        edition.prefix,
+        locale ?? current?.locale,
+        sources.filter((entry) => entry.prefix === edition.prefix),
+        fallbackLocale
+      )
+    );
+}

package/app/utils/version-choices.ts

@@ -45,6 +45,8 @@ export function versionChoices(
   // from the URL segment.
   if (configured?.length) return configured;
 
+  const editions = new Set<string>();
+
   return sources
     .filter(
       (source) =>
@@ -52,6 +54,14 @@ export function versionChoices(
         source.repo === current?.repo &&
         sameArtefact(source, current)
     )
+    .filter((source) => {
+      // Repository and artefact are scoped above; translations share the
+      // edition's version and target, while keeping separate collections.
+      const edition = JSON.stringify([source.version, source.prefix || '/']);
+      if (editions.has(edition)) return false;
+      editions.add(edition);
+      return true;
+    })
     .map((source) => ({
       label: source.version!,
       to: source.prefix || '/',

package/nuxt.config.ts

@@ -376,10 +376,13 @@ export default defineNuxtConfig({
 
   /**
    * nuxt-seo-utils, whose defaults are written for a site that sets no head
-   * tags of its own. Three of them are wrong HERE, and each for a reason this
-   * layer cannot design away.
+   * tags of its own. These defaults need adjusting for this layer's rendering.
    */
   seo: {
+    // MDC hydrates its Shiki <style> text from the Content payload. Rewriting
+    // only the prerendered HTML makes that text differ on the client.
+    minify: false,
+
     /**
      * A LOCALE PREFIX IS CASE-SENSITIVE. i18n routes this site's locales under
      * their own codes — `/de-DE/guides`, `/pt-BR/guides` — and lowercasing a

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@kirchdev/duxt",
-  "version": "0.1.1-dev-main.12-4d33ebf",
+  "version": "0.1.1-dev-main.30-1e18e2e",
   "description": "Nuxt documentation layer on Content v3 — multi-repo, versioned docs from one compact source list.",
   "keywords": [
     "content-v3",

package/public/devtools/checks.html

@@ -238,7 +238,7 @@
     <p class="hint">The build validator, run against what the site is serving now.</p>
     <div class="stats"><div class="stat "><b>34</b><span>pages checked</span></div><div class="stat "><b>6</b><span>collections</span></div><div class="stat ok"><b>0</b><span>errors</span></div><div class="stat warn"><b>5</b><span>warnings</span></div></div><h2>Warnings</h2><div class="scroll"><table>
     <thead><tr><th scope="col"></th><th scope="col">Warning</th></tr></thead>
-    <tbody><tr><td><span class="tag warn">warn</span></td><td>the generated section &quot;Releases&quot; (CHANGELOG.md): the heading &quot;1.3 (Feb 2026)&quot; on line 41 reads like a release but does not parse as one, so it became part of the release above it instead of a page of its own. A release heading is a version, optionally followed by a date in parentheses: `## 1.4.0 (2024-02-01)`.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_sdk/3.reference/2.errors.md">&quot;docs_sdk/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_de_sdk%2Fde%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_de_sdk/de/3.reference/2.errors.md">&quot;docs_de_sdk/de/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk_v1_9%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_sdk_v1_9/3.reference/2.errors.md">&quot;docs_sdk_v1_9/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F1.getting-started%2Findex.md" target="_blank" title="/srv/acme-docs/docs_sdk/1.getting-started/index.md">&quot;docs_sdk/1.getting-started/index.md&quot;</a> links to &quot;/guides/cacheing&quot;, which no page serves.</td></tr></tbody>
+    <tbody><tr><td><span class="tag warn">warn</span></td><td>the generated section &quot;Releases&quot; (CHANGELOG.md): the heading &quot;1.3 (Feb 2026)&quot; on line 41 reads like a release but does not parse as one, so it became part of the release above it instead of a page of its own. A release heading is a version, optionally followed by a date in parentheses: `## 1.4.0 (2024-02-01)`.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_sdk/3.reference/2.errors.md">&quot;docs_sdk/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_de_sdk%2Fde%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_de_sdk/de/3.reference/2.errors.md">&quot;docs_de_sdk/de/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk_v1_9%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_sdk_v1_9/3.reference/2.errors.md">&quot;docs_sdk_v1_9/3.reference/2.errors.md&quot;</a> has no title and no description.</td></tr><tr><td><span class="tag warn">warn</span></td><td><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F1.getting-started%2Findex.md" target="_blank" title="/srv/acme-docs/docs_sdk/1.getting-started/index.md">&quot;docs_sdk/1.getting-started/index.md&quot;</a> links to &quot;/sdk/guides/cacheing&quot;, which no page serves.</td></tr></tbody>
   </table></div><h2>Translations</h2><ul class="steps"><li><strong>de under &quot;/sdk&quot;: 6/8 pages</strong></li><li class="dim" style="margin-left:1.5rem"><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F2.guides%2F2.caching.md" target="_blank" title="/srv/acme-docs/docs_sdk/2.guides/2.caching.md">&quot;docs_sdk/2.guides/2.caching.md&quot;</a> has no de translation.</li><li class="dim" style="margin-left:1.5rem"><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk%2F4.changelog.md" target="_blank" title="/srv/acme-docs/docs_sdk/4.changelog.md">&quot;docs_sdk/4.changelog.md&quot;</a> has no de translation.</li><li><strong>de under &quot;/sdk/v1.9&quot;: 5/7 pages</strong></li><li class="dim" style="margin-left:1.5rem"><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk_v1_9%2F3.reference%2F2.errors.md" target="_blank" title="/srv/acme-docs/docs_sdk_v1_9/3.reference/2.errors.md">&quot;docs_sdk_v1_9/3.reference/2.errors.md&quot;</a> has no de translation.</li><li class="dim" style="margin-left:1.5rem"><a class="file" href="/__nuxt_devtools__/open-in-editor?file=%2Fsrv%2Facme-docs%2Fdocs_sdk_v1_9%2F4.changelog.md" target="_blank" title="/srv/acme-docs/docs_sdk_v1_9/4.changelog.md">&quot;docs_sdk_v1_9/4.changelog.md&quot;</a> has no de translation.</li></ul>
   </main>
   <script>

package/public/devtools/config.html

@@ -353,6 +353,7 @@
     <span class="j-key">&quot;repository&quot;</span>: <span class="j-str">&quot;acme/cli&quot;</span>,
     <span class="j-key">&quot;repositoryUrl&quot;</span>: <span class="j-str">&quot;https://github.com/acme/cli&quot;</span>,
     <span class="j-key">&quot;path&quot;</span>: <span class="j-str">&quot;docs&quot;</span>,
+    <span class="j-key">&quot;locale&quot;</span>: <span class="j-str">&quot;en&quot;</span>,
     <span class="j-key">&quot;isDefaultLocale&quot;</span>: <span class="j-word">true</span>,
     <span class="j-key">&quot;status&quot;</span>: <span class="j-str">&quot;current&quot;</span>,
     <span class="j-key">&quot;history&quot;</span>: <span class="j-word">false</span>

package/sections-changelog.ts

@@ -192,13 +192,15 @@ function parseChangelog(
   context: DuxtSectionContext
 ): DuxtSectionPage[] {
   const lines = artefact.split(/\r?\n/);
-
-  if (granularityOf(context.options) === 'flat') return [flat(lines, context)];
-
   const headings = headingsOf(lines);
-
   const starts = headings.filter((heading) => release(heading.text));
 
+  const newest = starts[0] ? release(starts[0].text)?.version : undefined;
+
+  if (granularityOf(context.options) === 'flat') {
+    return [flat(lines, context, newest)];
+  }
+
   reportNearMisses(headings, starts, context);
   const releases: Release[] = starts.map((heading, index) => {
     const parsed = release(heading.text)!;
@@ -236,11 +238,15 @@ function parseChangelog(
  * exactly where the release tool put it — which is what "unchanged" has to
  * mean, or the mode is not the escape hatch it exists to be.
  */
-function flat(lines: string[], context: DuxtSectionContext): DuxtSectionPage {
+function flat(
+  lines: string[],
+  context: DuxtSectionContext,
+  newest?: string
+): DuxtSectionPage {
   return {
     file: 'index.md',
     body: [
-      frontmatter({ title: context.label }),
+      frontmatter({ title: context.label, release: newest }),
       '',
       ...trim(withoutTitle(lines)),
       ''
@@ -437,7 +443,11 @@ function index(
   return {
     file: 'index.md',
     body: [
-      frontmatter({ title: context.label }),
+      // The header stays outside this component, so it cannot read the MDC
+      // props below. Keep the newest release beside the page title instead:
+      // Content exposes frontmatter on the page query that `DuxtVersion` uses,
+      // and parsing the file again there would make the two answers drift.
+      frontmatter({ title: context.label, release: releases[0]?.version }),
       '',
       // NO `<h1>` OF ITS OWN. The page draws the docs header — breadcrumb,
       // title, description, the copy control beside it — for exactly the

package/sections-resolve.ts

@@ -22,6 +22,7 @@ import type {
   DuxtSourcesOptions
 } from './sources-resolve';
 import {
+  assertCollectionIdentities,
   expandSources,
   identifier,
   resolveSources,
@@ -367,10 +368,16 @@ export function resolveGeneratedSections(
   // Claimed per locale, exactly as `resolveSources` claims its own prefixes:
   // two languages serving one prefix is not a collision, it is the point.
   const taken = new Map<string, string>(
-    resolved.map((entry) => [
-      `${entry.locale ?? ''}|${entry.prefix}`,
-      `the documentation at "${entry.prefix || '/'}"`
-    ])
+    resolved.flatMap((entry, index) =>
+      expanded[index]!.source.content === false
+        ? []
+        : [
+            [
+              `${entry.locale ?? ''}|${entry.prefix}`,
+              `the documentation at "${entry.prefix || '/'}"`
+            ] as [string, string]
+          ]
+    )
   );
 
   // Counted over the whole list rather than per source, so the identity is
@@ -539,6 +546,10 @@ export function resolveGeneratedSections(
     }
   });
 
+  assertCollectionIdentities([
+    ...resolved.filter((_, index) => expanded[index]!.source.content !== false),
+    ...generated
+  ]);
   return generated;
 }
 
@@ -704,8 +715,11 @@ export function duxtManifest(
   options: DuxtSourcesOptions = {},
   types: DuxtSectionTypes = duxtSectionTypes()
 ): DuxtResolvedSource[] {
+  const resolved = resolveSources(sources, options);
+  const expanded = expandSources(sources, options);
+
   return [
-    ...resolveSources(sources, options),
+    ...resolved.filter((_, index) => expanded[index]!.source.content !== false),
     ...resolveGeneratedSections(sources, options, types)
   ];
 }

package/server/middleware/raw-markdown.ts

@@ -1,4 +1,7 @@
 import { queryCollection } from '@nuxt/content/nitro';
+import { defineEventHandler, setHeader } from 'h3';
+import { splitLocalePath } from '../../app/utils/locale-path';
+import { sourcesForRoute } from '../../sources-resolve';
 import { duxtDefaults, mergeDuxtConfig } from '../../app/utils/duxt-config';
 import { stripFrontmatter } from '../utils/duxt-server-text';
 
@@ -21,31 +24,42 @@ export default defineEventHandler(async (event) => {
   const appConfig = useAppConfig() as { duxt?: Partial<DuxtConfig> };
   const duxt = mergeDuxtConfig(appConfig.duxt, duxtDefaults);
 
-  const wanted = stripLocale(path.slice(0, -'.md'.length));
-
-  // Longest prefix first, exactly as the app resolves a route: `/app/v2` beats
-  // `/app` on `/app/v2/guide`.
-  const sources = [...(duxt.resolvedSources ?? [])].sort(
-    (a, b) => b.prefix.length - a.prefix.length
+  const i18n = (
+    useRuntimeConfig(event).public as {
+      i18n?: {
+        locales?: ({ code: string } | string)[];
+        defaultLocale?: string;
+      };
+    }
+  ).i18n;
+  const { path: wanted, locale } = splitLocalePath(
+    path.slice(0, -'.md'.length),
+    (i18n?.locales ?? []).map((entry) =>
+      typeof entry === 'string' ? entry : entry.code
+    )
+  );
+  // Nuxt i18n loads the consumer's merged Vue I18n config in its request hook.
+  // Browser-language detection's fallback is a different policy.
+  const fallbackLocale = event.context.nuxtI18n?.vueI18nOptions
+    ?.fallbackLocale as string | string[] | undefined;
+  const sources = sourcesForRoute(
+    wanted,
+    locale ?? i18n?.defaultLocale,
+    duxt.resolvedSources ?? [],
+    fallbackLocale
   );
 
-  const source =
-    sources.find(
-      (entry) =>
-        !entry.prefix ||
-        wanted === entry.prefix ||
-        wanted.startsWith(`${entry.prefix}/`)
-    ) ?? sources[0];
-
-  if (!source) return;
-
-  const page = await queryCollection(
-    event,
-    source.collection as Parameters<typeof queryCollection>[1]
-  )
-    .path(wanted)
-    .select('title', 'rawbody')
-    .first();
+  let page;
+  for (const source of sources) {
+    page = await queryCollection(
+      event,
+      source.collection as Parameters<typeof queryCollection>[1]
+    )
+      .path(wanted)
+      .select('title', 'rawbody')
+      .first();
+    if (page) break;
+  }
 
   // No page is not this middleware's error to raise: falling through lets the
   // app answer with its own 404, which knows how to suggest a near miss.
@@ -57,30 +71,3 @@ export default defineEventHandler(async (event) => {
   setHeader(event, 'content-type', 'text/markdown; charset=utf-8');
   return stripFrontmatter(body).trim();
 });
-
-/**
- * The locale segment, off.
- *
- * The browser is on `/de-DE/guide/deploying`; the page is `/guide/deploying`.
- * Same distinction `stripLocalePrefix` makes in the app, made again here
- * because Nitro has no i18n composable to ask.
- */
-function stripLocale(path: string): string {
-  const first = path.split('/')[1];
-  if (!first) return path;
-
-  const locales = (
-    useRuntimeConfig().public as {
-      i18n?: { locales?: ({ code: string } | string)[] };
-    }
-  ).i18n?.locales;
-
-  const codes = (locales ?? []).map((locale) =>
-    typeof locale === 'string' ? locale : locale.code
-  );
-
-  if (!codes.includes(first)) return path;
-
-  const rest = path.slice(first.length + 1);
-  return rest.startsWith('/') ? rest : rest || '/';
-}

package/server/routes/llms-full.txt.get.ts

@@ -1,4 +1,4 @@
-import { queryCollection } from '@nuxt/content/nitro';
+import { llmsPages } from '../utils/llms-pages';
 // Imported by path, not auto-import: app/ belongs to the Vue app, and Nitro
 // does not see its utils. The defaults have to come from the same file the
 // pages use, or the two descriptions drift apart.
@@ -27,19 +27,7 @@ export default defineEventHandler(async (event) => {
     mergeDuxtConfig(appConfig.duxt, duxtDefaults)
   );
 
-  const collections = duxt.resolvedSources?.length
-    ? duxt.resolvedSources.map((source) => source.collection)
-    : ['docs'];
-
-  const pages = (
-    await Promise.all(
-      collections.map((name) =>
-        queryCollection(event, name as Parameters<typeof queryCollection>[1])
-          .select('path', 'title', 'description', 'rawbody')
-          .all()
-      )
-    )
-  ).flat();
+  const pages = await llmsPages(event, duxt.resolvedSources);
 
   const origin = getRequestURL(event).origin;
 

package/server/routes/llms.txt.get.ts

@@ -1,4 +1,4 @@
-import { queryCollection } from '@nuxt/content/nitro';
+import { llmsPages } from '../utils/llms-pages';
 // Imported by path, not auto-import: app/ belongs to the Vue app, and Nitro
 // does not see its utils. The defaults have to come from the same file the
 // pages use, or the two descriptions drift apart.
@@ -22,21 +22,7 @@ export default defineEventHandler(async (event) => {
 
   // Every collection the manifest names, not just `docs`: a versioned site
   // has none by that name, and llms.txt is the whole site's index.
-  const collections = duxt.resolvedSources?.length
-    ? duxt.resolvedSources.map((source) => source.collection)
-    : ['docs'];
-
-  const pages = (
-    await Promise.all(
-      collections.map((name) =>
-        // Cast from Content's own signature: the collection name is data
-        // from the manifest, and the key union is generated per site.
-        queryCollection(event, name as Parameters<typeof queryCollection>[1])
-          .select('path', 'title', 'description')
-          .all()
-      )
-    )
-  ).flat();
+  const pages = await llmsPages(event, duxt.resolvedSources);
 
   const origin = getRequestURL(event).origin;
 

package/server/utils/llms-pages.ts

@@ -0,0 +1,87 @@
+import { queryCollection } from '@nuxt/content/nitro';
+import type { H3Event } from 'h3';
+import {
+  sourcesForRoute,
+  type DuxtResolvedSource
+} from '../../sources-resolve';
+
+/** Enumerate public pages, selecting the same collection chain as HTML. */
+export async function llmsPages(
+  event: H3Event,
+  sources: DuxtResolvedSource[] = []
+) {
+  const i18n = (
+    useRuntimeConfig(event).public as unknown as {
+      i18n?: {
+        locales?: (string | { code: string })[];
+        defaultLocale?: string;
+        strategy?: string;
+      };
+    }
+  ).i18n;
+  const fallbackLocale = event.context.nuxtI18n?.vueI18nOptions
+    ?.fallbackLocale as string | string[] | undefined;
+  const codes = (i18n?.locales ?? []).map((locale) =>
+    typeof locale === 'string' ? locale : locale.code
+  );
+  const defaultLocale = i18n?.defaultLocale ?? codes[0];
+  const strategy = i18n?.strategy ?? 'prefix_except_default';
+  const locales =
+    strategy === 'no_prefix' || !codes.length ? [defaultLocale] : codes;
+  const collections = sources.length
+    ? [...new Set(sources.map((source) => source.collection))]
+    : ['docs'];
+  const entries = await Promise.all(
+    collections.map(
+      async (name) =>
+        [
+          name,
+          await queryCollection(
+            event,
+            name as Parameters<typeof queryCollection>[1]
+          )
+            .select('path', 'title', 'description', 'rawbody')
+            .all()
+        ] as const
+    )
+  );
+  const pagesByCollection = new Map(
+    entries.map(([name, pages]) => [
+      name,
+      new Map(
+        pages.filter((page) => page.path).map((page) => [page.path, page])
+      )
+    ])
+  );
+  const paths = new Set(
+    entries.flatMap(([, pages]) =>
+      pages.map((page) => page.path).filter(Boolean)
+    )
+  );
+  const result = new Map<string, (typeof entries)[number][1][number]>();
+
+  for (const locale of locales) {
+    for (const path of paths) {
+      const chain = sources.length
+        ? sourcesForRoute(path, locale, sources, fallbackLocale).map(
+            (source) => source.collection
+          )
+        : ['docs'];
+      const page = chain
+        .map((name) => pagesByCollection.get(name)?.get(path))
+        .find(Boolean);
+      if (!page) continue;
+      const prefixed =
+        locale &&
+        strategy !== 'no_prefix' &&
+        (strategy !== 'prefix_except_default' || locale !== defaultLocale);
+      const publicPath = prefixed
+        ? `/${locale}${path === '/' ? '' : path}`
+        : path;
+      result.set(publicPath, { ...page, path: publicPath });
+      if (strategy === 'prefix_and_default' && locale === defaultLocale)
+        result.set(path, { ...page, path });
+    }
+  }
+  return [...result.values()].sort((a, b) => a.path.localeCompare(b.path));
+}

package/sources-git.ts

@@ -1,6 +1,11 @@
 import { execFileSync } from 'node:child_process';
 import type { DuxtSource } from './sources-resolve';
-import { isLatestRef, newestTag, repoUrl } from './sources-resolve';
+import {
+  expandSources,
+  isLatestRef,
+  newestTag,
+  repoUrl
+} from './sources-resolve';
 
 /**
  * Resolve the `latest` shorthand into the tag it means.
@@ -81,6 +86,8 @@ function tagsOf(repo: string | undefined): string[] {
  * resolver itself stays pure and testable — it never learns that git exists.
  */
 export function resolveLatestRefs(sources: DuxtSource[]): DuxtSource[] {
+  // Reject local refs before a missing tag can hide the configuration error.
+  expandSources(sources);
   return sources.map((source) => {
     if (!source.refs?.some(isLatestRef)) return source;
 

package/sources-resolve.ts

@@ -12,10 +12,18 @@ import type {
 export interface DuxtSource {
   /** Folder holding the Markdown, relative to the repository root. */
   path?: string;
-  /** `owner/name` or a full git URL. Omitted means this repository. */
+  /**
+   * Whether this source's Markdown is published as documentation pages.
+   *
+   * A source can carry generated sections without publishing its own tree. That
+   * lets a versioned documentation source and a generated artefact share their
+   * default URL prefix without declaring two page collections for it.
+   */
+  content?: boolean;
+  /** `owner/name` or a full git URL. Omitted reads the local checkout. */
   repo?: string;
   /**
-   * Refs to publish as versions. Omitted means the current checkout.
+   * Refs to publish as versions. Requires an explicit source or locale repo.
    *
    * A bare string is a branch. A tag has to say so — git keeps the two in
    * separate namespaces, and asking for a tag under refs/heads fails the
@@ -33,7 +41,8 @@ export interface DuxtSource {
    * The DEFAULT locale is the exception: it is the tree in `path` itself, with
    * no folder, so listing it changes nothing. That is what keeps this key
    * additive — a site that adds `locales` does not move the pages it already
-   * serves. Which one is the default comes from `defaultLocale`.
+   * serves. Which one is the default comes from `defaultLocale`. Omitting
+   * `locales` serves that default language too.
    */
   locales?: DuxtSourceLocale[];
   /**
@@ -166,7 +175,7 @@ export type DuxtSourceLocale =
       path?: string;
       /** A repository of its own — `owner/name` or a git URL. */
       repo?: string;
-      /** A ref of its own, when the translation is versioned separately. */
+      /** A ref of its own; requires an explicit source or locale repo. */
       ref?: DuxtRef;
     };
 
@@ -488,12 +497,16 @@ export function expandSources(
 
   return sources.flatMap((source) =>
     (source.refs?.length ? source.refs : [undefined]).flatMap((ref) =>
-      localesOf(source, ref).map((locale) => ({
-        source,
-        ref,
-        locale,
-        effective: localeEntry(source, locale, defaultLocale)
-      }))
+      localesOf(source, ref).map((locale) => {
+        const effective = localeEntry(source, locale, defaultLocale);
+        if (!effective.repo && (effective.ref ?? ref)) {
+          throw new Error(
+            `duxt: source "${source.path ?? 'docs'}" reads the local checkout and cannot select a ref. ` +
+              'Set an explicit repo to publish Git refs, or use version folders without refs.'
+          );
+        }
+        return { source, ref, locale, effective };
+      })
     )
   );
 }
@@ -561,7 +574,7 @@ export function resolveSources(
     const name = effectiveRef ? refName(effectiveRef) : source.version;
     const label =
       (ref && typeof ref === 'object' ? ref.label : undefined) ?? source.label;
-    const code = locale ? localeCode(locale) : undefined;
+    const code = locale ? localeCode(locale) : defaultLocale;
     const isDefaultLocale = !code || code === defaultLocale;
     const version = name ? slugify(label ?? name) : undefined;
     const isDefault = !name || name === defaultRef;
@@ -584,21 +597,23 @@ export function resolveSources(
 
     // Claimed per locale: two languages serving one prefix is not a collision,
     // it is the point.
-    const claim = `${code ?? ''}|${prefix}`;
-    const previous = taken.get(claim);
-    if (previous) {
-      // The one ambiguity the build-time decision leaves: a docs folder named
-      // like a repository or a version. Rejected rather than resolved silently.
-      throw new Error(
-        `duxt: two sources resolve to the same URL prefix "${prefix || '/'}" ` +
-          `(${previous} and ${source.repo ?? 'this repository'}${ref ? `@${ref}` : ''}). ` +
-          'Give one of them a `slug` or a `label`.'
+    if (source.content !== false) {
+      const claim = `${code ?? ''}|${prefix}`;
+      const previous = taken.get(claim);
+      if (previous) {
+        // The one ambiguity the build-time decision leaves: a docs folder named
+        // like a repository or a version. Rejected rather than resolved silently.
+        throw new Error(
+          `duxt: two sources resolve to the same URL prefix "${prefix || '/'}" ` +
+            `(${previous} and ${source.repo ?? 'this repository'}${ref ? `@${ref}` : ''}). ` +
+            'Give one of them a `slug` or a `label`.'
+        );
+      }
+      taken.set(
+        claim,
+        `${source.repo ?? 'this repository'}${name ? `@${name}` : ''}`
       );
     }
-    taken.set(
-      claim,
-      `${source.repo ?? 'this repository'}${name ? `@${name}` : ''}`
-    );
 
     resolved.push({
       collection,
@@ -631,6 +646,9 @@ export function resolveSources(
     });
   }
 
+  assertCollectionIdentities(
+    resolved.filter((_, index) => expanded[index]!.source.content !== false)
+  );
   return resolved;
 }
 
@@ -906,3 +924,41 @@ function isInsidePrefix(path: string, prefix: string): boolean {
 
   return path === prefix || path.startsWith(`${prefix}/`);
 }
+
+/** Validate names before any collection map can overwrite a declaration. */
+export function assertCollectionIdentities(
+  entries: DuxtResolvedSource[]
+): void {
+  const taken = new Map<string, string>();
+  const claim = (name: string, declaration: string) => {
+    const previous = taken.get(name);
+    if (previous !== undefined) {
+      throw new Error(
+        `duxt: collection "${name}" is claimed by both ${previous} and ${declaration}. ` +
+          'Give one declaration a distinct `slug` or `label`.'
+      );
+    }
+    taken.set(name, declaration);
+  };
+
+  for (const entry of entries) {
+    const kind = entry.generated
+      ? `generated section "${entry.generated.label}"`
+      : 'documentation';
+    claim(
+      entry.collection,
+      `${kind} "${entry.path}" at "${entry.prefix || '/'}"` +
+        (entry.locale ? ` (locale "${entry.locale}")` : '')
+    );
+  }
+
+  // Shared partials are one declaration per language, even across sources.
+  const locales = new Set(
+    entries
+      .filter((entry) => !entry.generated)
+      .map((entry) => (entry.isDefaultLocale ? undefined : entry.locale))
+  );
+  for (const locale of locales) {
+    claim(partialsCollection(locale), `partials for "${locale ?? 'default'}"`);
+  }
+}

package/sources.ts

@@ -37,6 +37,8 @@ export const pageSchema = z.object({
   icon: z.string().optional(),
   /** `landing` renders the page without the docs chrome. */
   layout: z.string().optional(),
+  /** The latest release of a generated changelog overview. */
+  release: z.string().optional(),
   /** false hides the page from the navigation. */
   navigation: z.boolean().optional(),
   /**
@@ -153,6 +155,7 @@ export function duxtSources(
 
   resolved.forEach((entry, index) => {
     const { source, ref, effective } = expanded[index]!;
+    if (source.content === false) return;
 
     // A locale entry may carry a ref of its own — a translation repository
     // that tags on its own schedule.
@@ -228,7 +231,8 @@ function partialFolders(
   const seen = new Set<string>();
 
   resolved.forEach((entry, index) => {
-    const { effective } = expanded[index]!;
+    const { source, effective } = expanded[index]!;
+    if (source.content === false) return;
     const key = entry.isDefaultLocale ? undefined : entry.locale;
 
     // One entry per REPOSITORY AND FOLDER, not per version: a partial is a

package/validate-report.ts

@@ -10,6 +10,7 @@
  */
 import { reservedSegments } from './sources-resolve';
 import { packageCommandIssues } from './app/utils/package-command';
+import { resolveDocumentationPath } from './app/utils/documentation-link';
 
 export interface PageRecord {
   collection: string;
@@ -203,9 +204,9 @@ export function report(
   //    verify, and checking it would put the network in the build.
   //
   //    Resolved exactly as `ProseA` resolves them at render time: an absolute
-  //    path written in a page is relative to that page's OWN source, so it is
-  //    tried under the source's prefix first and bare second. Checking only the
-  //    bare form reports every correct link on a prefixed site.
+  //    path written in a page is relative to that page's OWN source. `~/` is
+  //    the one explicit website-root form. Checking a normal path bare as a
+  //    fallback would green-light a rendered 404 from a prefixed source.
   //
   //    PER LANGUAGE, and that is not a refinement. Every language of one source
   //    serves IDENTICAL content paths — the locale lives in front of the URL,
@@ -259,9 +260,15 @@ export function report(
 
     for (const link of page.links) {
       const { href } = link;
-      if (!href.startsWith('/') && !href.startsWith('#')) continue;
+      if (
+        !href.startsWith('/') &&
+        !href.startsWith('~/') &&
+        !href.startsWith('#')
+      )
+        continue;
 
-      const [target, fragment] = href.split('#');
+      const [targetAndQuery, fragment] = href.split('#');
+      const [target, query] = targetAndQuery!.split('?');
 
       // DECODED, because the two halves are written in different alphabets. A
       // heading's id is the text as it stands — `icônes` — while the link
@@ -269,20 +276,22 @@ export function report(
       // accented anchor on the site as missing and told the author to point at
       // a heading that was already there.
       const anchor = fragment && decodeAnchor(fragment);
-      const destination = target
-        ? (resolve(`${prefix}${target}`, page) ?? resolve(target, page))
-        : page;
+      const renderedTarget = target
+        ? resolveDocumentationPath(target, prefix)
+        : target;
+      const renderedHref = `${renderedTarget}${query ? `?${query}` : ''}${fragment ? `#${fragment}` : ''}`;
+      const destination = renderedTarget ? resolve(renderedTarget, page) : page;
 
-      if (target && !destination) {
+      if (renderedTarget && !destination) {
         warnings.push(
-          `"${page.file}" links to "${href}", which no page serves.`
+          `"${page.file}" links to "${renderedHref}", which no page serves.`
         );
         continue;
       }
 
       if (anchor && destination && !destination.anchors.has(anchor)) {
         warnings.push(
-          `"${page.file}" links to "${href}", but that page has no "${anchor}" heading.`
+          `"${page.file}" links to "${renderedHref}", but that page has no "${anchor}" heading.`
         );
       }
     }