@kirchdev/duxt 0.1.1-dev.29-765cae3 → 0.2.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/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/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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@kirchdev/duxt",
-  "version": "0.1.1-dev.29-765cae3",
+  "version": "0.2.0",
   "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/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

@@ -368,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
@@ -540,7 +546,10 @@ export function resolveGeneratedSections(
     }
   });
 
-  assertCollectionIdentities([...resolved, ...generated]);
+  assertCollectionIdentities([
+    ...resolved.filter((_, index) => expanded[index]!.source.content !== false),
+    ...generated
+  ]);
   return generated;
 }
 
@@ -706,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,5 @@
 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';

package/sources-resolve.ts

@@ -12,6 +12,14 @@ import type {
 export interface DuxtSource {
   /** Folder holding the Markdown, relative to the repository root. */
   path?: string;
+  /**
+   * 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;
   /**
@@ -589,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,
@@ -636,7 +646,9 @@ export function resolveSources(
     });
   }
 
-  assertCollectionIdentities(resolved);
+  assertCollectionIdentities(
+    resolved.filter((_, index) => expanded[index]!.source.content !== false)
+  );
   return resolved;
 }
 

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.`
         );
       }
     }