@kirchdev/duxt 0.1.0

package/app/utils/file-icons.ts

@@ -0,0 +1,62 @@
+/**
+ * Icon for a filename or a language id.
+ *
+ * The vscode-icons collection is the one that actually has an icon per
+ * ecosystem; lucide covers the fallbacks. Used by both the code block header
+ * and the file tree, so a `.ts` file looks the same in either.
+ */
+const byExtension: Record<string, string> = {
+  bash: 'vscode-icons:file-type-shell',
+  css: 'vscode-icons:file-type-css',
+  env: 'vscode-icons:file-type-dotenv',
+  go: 'vscode-icons:file-type-go',
+  html: 'vscode-icons:file-type-html',
+  jpg: 'vscode-icons:file-type-image',
+  javascript: 'vscode-icons:file-type-js',
+  js: 'vscode-icons:file-type-js',
+  json: 'vscode-icons:file-type-json',
+  jsonc: 'vscode-icons:file-type-json',
+  md: 'vscode-icons:file-type-markdown',
+  mdc: 'vscode-icons:file-type-markdown',
+  mjs: 'vscode-icons:file-type-js',
+  php: 'vscode-icons:file-type-php',
+  png: 'vscode-icons:file-type-image',
+  python: 'vscode-icons:file-type-python',
+  py: 'vscode-icons:file-type-python',
+  rs: 'vscode-icons:file-type-rust',
+  sh: 'vscode-icons:file-type-shell',
+  svg: 'vscode-icons:file-type-svg',
+  ts: 'vscode-icons:file-type-typescript',
+  typescript: 'vscode-icons:file-type-typescript',
+  toml: 'vscode-icons:file-type-toml',
+  vue: 'vscode-icons:file-type-vue',
+  yaml: 'vscode-icons:file-type-yaml',
+  yml: 'vscode-icons:file-type-yaml'
+};
+
+/** Whole filenames worth their own icon, checked before the extension. */
+const byName: Record<string, string> = {
+  'package.json': 'vscode-icons:file-type-npm',
+  'pnpm-lock.yaml': 'vscode-icons:file-type-pnpm',
+  'pnpm-workspace.yaml': 'vscode-icons:file-type-pnpm',
+  'nuxt.config.ts': 'vscode-icons:file-type-nuxt',
+  'content.config.ts': 'vscode-icons:file-type-nuxt',
+  'app.config.ts': 'vscode-icons:file-type-nuxt',
+  'tsconfig.json': 'vscode-icons:file-type-tsconfig',
+  dockerfile: 'vscode-icons:file-type-docker',
+  '.gitignore': 'vscode-icons:file-type-git'
+};
+
+export function fileIcon(input?: string, fallback = 'lucide:file') {
+  if (!input) return fallback;
+
+  const name = input.split('/').pop()?.toLowerCase() ?? '';
+  if (byName[name]) return byName[name];
+
+  const extension = name.includes('.') ? name.split('.').pop()! : name;
+  return byExtension[extension] ?? fallback;
+}
+
+export function folderIcon(open = false) {
+  return open ? 'lucide:folder-open' : 'lucide:folder';
+}

package/app/utils/generated-sections.ts

@@ -0,0 +1,190 @@
+/**
+ * What the app does with a generated section.
+ *
+ * A section is an ordinary collection at a prefix of its own, so almost nothing
+ * in the theme has to know it exists — the collection lookup, the search, the
+ * breadcrumb and the navigation tree all work off the manifest and were not
+ * touched. Two things do not follow from the collection, and they are here:
+ * WHERE its navbar entry goes, and WHICH LAYOUT its pages render in.
+ *
+ * Pure, and beside the resolver's other path arithmetic for the same reason:
+ * every version bug this layer has had came from prefix work done inline in a
+ * component, where it could only be checked by clicking.
+ */
+// Named rather than auto-imported: a test runs this file outside Nuxt, where
+// nothing fills the auto-imports in.
+import { sourceForPath } from './version-paths';
+
+/**
+ * The config with each generated section's navbar entry in place.
+ *
+ * Appended here rather than written into `appConfig` by the build, and that is
+ * not a detail: the generated template merges `appConfig` BEHIND every
+ * `app.config.ts`, and `mergeDuxtConfig` replaces an array rather than
+ * appending to it — so a consumer naming `sections` at all would have replaced
+ * the entry the build had just added, and the section would be unreachable on
+ * exactly the sites that configure the most.
+ *
+ * A section already listed by hand is left alone, so a consumer who wants it
+ * somewhere else in the row simply writes it there. "Listed by hand" is asked
+ * of the SECTION rather than of one URL: the consumer wrote the entry at the
+ * position they were reading, and a `per-version` section is at a different URL
+ * on every other version — so the per-URL question answered no there and
+ * appended a second entry with the same label.
+ *
+ * ONE DECLARATION IS ONE ENTRY, whatever it resolved to. A section is a
+ * collection per version and per locale, so `per-version` and `per-locale`
+ * reach here as several manifest entries for the same declared section — and
+ * the row is "the top-level parts of the documentation", not a list of the
+ * versions of one. So the entry is resolved against the section the reader is
+ * currently in, exactly as `DuxtVersion` and `useDuxtVersion` resolve theirs,
+ * with a de-dupe by `to` underneath it: two entries pointing at one URL are one
+ * link twice, and under `DuxtHeader`'s label key, one Vue key twice.
+ *
+ * Which entries are one declaration is READ OFF THE MANIFEST, never guessed —
+ * see `DuxtGeneratedMeta.declaration` for what guessing it cost.
+ */
+export function withGeneratedSections(
+  config: DuxtConfig,
+  path = '/'
+): DuxtConfig {
+  const sources = config.resolvedSources ?? [];
+  const declarations = declarationsIn(sources);
+
+  if (!declarations.length) return config;
+
+  const base = readerBase(path, sources);
+
+  const entriesFor = (
+    placement: DuxtSectionPlacementInput,
+    existing: DuxtLink[]
+  ) => {
+    // Seeded from what the consumer wrote and UPDATED as entries are added, so
+    // the de-dupe holds among the generated entries as well as against the
+    // hand-written ones. Building it once before the map was the bug: it
+    // answered for the consumer's list only.
+    const taken = new Set(existing.map((entry) => entry.to).filter(Boolean));
+    const entries: DuxtLink[] = [];
+
+    for (const declaration of declarations) {
+      const meta = declaration[0]!.generated!;
+      if (meta.navigation !== placement) continue;
+
+      // ANY position of this declaration counts as already in the row, not just
+      // the one this reader would be given: a section listed by hand is listed,
+      // and the entry `to` resolves to is always one of these prefixes, so this
+      // is the de-dupe by URL as well.
+      if (declaration.some((entry) => taken.has(entry.prefix))) continue;
+
+      const to = entryPath(declaration, base);
+
+      taken.add(to);
+      entries.push({ label: meta.label, to, icon: meta.icon });
+    }
+
+    return entries;
+  };
+
+  const navigation = entriesFor('navigation', config.navigation ?? []);
+  const sections = entriesFor('sections', config.sections ?? []);
+
+  if (!navigation.length && !sections.length) return config;
+
+  return {
+    ...config,
+    // Only the row that gains something is rewritten: an empty array where the
+    // config had `undefined` is a different value, and the header reads both.
+    ...(navigation.length
+      ? { navigation: [...(config.navigation ?? []), ...navigation] }
+      : {}),
+    ...(sections.length
+      ? { sections: [...(config.sections ?? []), ...sections] }
+      : {})
+  };
+}
+
+/**
+ * The manifest's generated entries, grouped into the declarations that made
+ * them, in the order the site declared them.
+ *
+ * A `Map` rather than a sort: the manifest already lists a declaration's
+ * entries together, and the grouping has to survive it not doing so.
+ */
+function declarationsIn(sources: DuxtResolvedSource[]): DuxtResolvedSource[][] {
+  const groups = new Map<number, DuxtResolvedSource[]>();
+
+  for (const source of sources) {
+    if (!source.generated) continue;
+
+    const group = groups.get(source.generated.declaration);
+    if (group) group.push(source);
+    else groups.set(source.generated.declaration, [source]);
+  }
+
+  return [...groups.values()];
+}
+
+/**
+ * The prefix the reader's DOCUMENTATION sits at — their repository and their
+ * version, with no section segment on the end.
+ *
+ * Inside a generated section the reader's version can only be read off that
+ * section's own prefix, so its slug is taken back off. `/v1.x/releases` is a
+ * reader on `v1.x`, and the row has to keep saying so.
+ */
+function readerBase(path: string, sources: DuxtResolvedSource[]): string {
+  const current = sourceForPath(path, sources);
+  if (!current) return '';
+
+  const own = current.generated ? `/${current.generated.slug}` : '';
+
+  return own && current.prefix.endsWith(own)
+    ? current.prefix.slice(0, -own.length)
+    : current.prefix;
+}
+
+/**
+ * Where one declared section's navbar entry points, from where the reader is.
+ *
+ * The entries handed in ARE the declaration — its versions and its languages,
+ * as the manifest recorded them. The reader's own base picks one of them.
+ */
+function entryPath(declaration: DuxtResolvedSource[], base: string): string {
+  const here = `${base}/${declaration[0]!.generated!.slug}`;
+
+  if (declaration.some((other) => other.prefix === here)) return here;
+
+  // Nothing at the reader's version: a `global` section has one entry and no
+  // version at all, and a version may simply have declared no artefact. The
+  // entry nearest the root is the default version's — the resolver adds a
+  // version segment for every version EXCEPT the one served without a prefix.
+  return declaration.reduce((nearest, other) =>
+    depth(other.prefix) < depth(nearest.prefix) ? other : nearest
+  ).prefix;
+}
+
+/** How many segments deep a prefix is; `''` is the root and therefore zero. */
+const depth = (prefix: string) => (prefix ? prefix.split('/').length - 1 : 0);
+
+/**
+ * The layout a route asks for, when it is inside a generated section.
+ *
+ * THE SHARED SLOT. Each type names its own layout and every type renders
+ * through this one lookup, which is what stops two types inventing two
+ * unrelated ways to escape the docs chrome. A type that names none renders in
+ * the ordinary chrome, and the lookup answers `undefined`.
+ *
+ * Filtered to the sections that name a layout before the prefix match, so a
+ * site whose types all render in the docs chrome does no work at all.
+ */
+export function generatedLayout(
+  path: string,
+  sources: DuxtResolvedSource[]
+): string | undefined {
+  const withLayout = sources.filter((source) => source.generated?.layout);
+  if (!withLayout.length) return undefined;
+
+  // Every entry here carries a prefix, so `sourceForPath` returns a genuine
+  // match or nothing — it has no prefixless source to fall back to.
+  return sourceForPath(path, withLayout)?.generated?.layout;
+}

package/app/utils/generated-toc.ts

@@ -0,0 +1,216 @@
+/**
+ * The contents column for a page whose headings a COMPONENT draws.
+ *
+ * Content builds `body.toc` from the Markdown headings it parsed, which is the
+ * whole outline of an ordinary page and none of the outline of a generated one:
+ * a release page's headings are the group names `ChangelogGroup` renders from a
+ * prop. Content sees a component call and nothing else, so `body.toc.links`
+ * comes back empty and the page had no contents column at all.
+ *
+ * So the outline is read back off the AST the page ships anyway — the same
+ * nodes `ContentRenderer` is about to draw, before it draws them. That keeps it
+ * SSR-safe and pure: no registry a child fills during render (which renders
+ * empty on the server and mismatches on hydration), and no second query.
+ *
+ * Anchors come from `changelog.ts`, which is also what the two components use,
+ * so a link here and the id it points at cannot drift apart.
+ */
+import { changelogAnchor, changelogLabel } from './changelog';
+
+export interface DuxtGeneratedTocLink {
+  id: string;
+  text: string;
+  depth: number;
+  children?: DuxtGeneratedTocLink[];
+}
+
+const HEADING = /^h([23])$/;
+
+/**
+ * A prop, whichever spelling it arrived in.
+ *
+ * Content writes a non-string prop under a `:`-prefixed key holding JSON — the
+ * same encoding MDC uses in a document — so `count` is `":count"` and
+ * `releases` is a JSON string. Read both, because which one a prop takes
+ * depends on the value the parser gave it and not on the component.
+ */
+function prop(props: Record<string, unknown>, name: string): unknown {
+  if (name in props) return props[name];
+
+  const raw = props[`:${name}`];
+  if (typeof raw !== 'string') return raw;
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The words a node shows, with its markup dropped. */
+function text(node: unknown): string {
+  if (typeof node === 'string') return node;
+  if (!Array.isArray(node)) return '';
+
+  return node.slice(2).map(text).join('');
+}
+
+/**
+ * Every entry the page's own AST names, in document order and flat.
+ *
+ * Depth follows what the page RENDERS rather than what the node is: a group is
+ * an `<h2>` on the release page, and a heading written under that group was
+ * promoted to `##` by the parser — so inside a group it is one level further
+ * in, or the column would claim both are siblings.
+ */
+function walk(nodes: unknown[], inside: boolean): DuxtGeneratedTocLink[] {
+  const links: DuxtGeneratedTocLink[] = [];
+
+  for (const node of nodes) {
+    if (!Array.isArray(node)) continue;
+
+    const [tag, ...rest] = node as unknown[];
+    if (typeof tag !== 'string') continue;
+
+    const props = (
+      rest[0] && typeof rest[0] === 'object' ? rest[0] : {}
+    ) as Record<string, unknown>;
+    const children = rest.slice(1);
+
+    if (tag === 'changelog-group') {
+      const name = String(prop(props, 'name') ?? '');
+      const id = changelogAnchor(name);
+
+      // The same words the heading itself draws — the anchor is still built
+      // from the file's own name, so the two cannot point apart.
+      if (id) links.push({ id, text: changelogLabel(name), depth: 2 });
+      links.push(...walk(children, true));
+      continue;
+    }
+
+    // The release OVERVIEW contributes nothing. Its versions are already the
+    // whole visible page — a column repeating the six lines the reader is
+    // looking at is a second copy of the list, not a way around it. What is
+    // left there is the aside's own links and the page's provenance, which is
+    // why the column is drawn on a page with no outline at all.
+    if (tag === 'changelog-releases') continue;
+
+    const heading = HEADING.exec(tag);
+    if (heading) {
+      const id = props.id;
+      if (typeof id === 'string' && id) {
+        links.push({
+          id,
+          text: text(node).trim(),
+          depth: inside ? 3 : Number(heading[1])
+        });
+      }
+      continue;
+    }
+
+    links.push(...walk(children, inside));
+  }
+
+  return links;
+}
+
+/** The flat list nested the way `DuxtToc` draws it: one level of children. */
+export function generatedToc(body: unknown): DuxtGeneratedTocLink[] {
+  const value = (body as { value?: unknown })?.value;
+  if (!Array.isArray(value)) return [];
+
+  const links: DuxtGeneratedTocLink[] = [];
+
+  for (const link of walk(value, false)) {
+    const parent = links.at(-1);
+
+    if (link.depth > 2 && parent) (parent.children ??= []).push(link);
+    else links.push({ ...link, depth: 2 });
+  }
+
+  return links;
+}
+
+/**
+ * Does this page open on a heading of its own?
+ *
+ * The one question that decides whether a generated page gets the DOCS HEADER —
+ * breadcrumb, title, description, the copy control beside it. A type whose
+ * parser writes an `<h1>` has said it draws its own (an endpoint wants its
+ * title beside a method chip, which no shell could know); one that writes none
+ * has a title and a trail like every other page and should look like one.
+ *
+ * Read off the artefact rather than declared as a flag on the type: the two
+ * cannot then disagree, and the failure a flag would have — an `<h1>` from the
+ * parser under an `<h1>` from the shell — is not expressible.
+ */
+export function generatedTitle(body: unknown): boolean {
+  const value = (body as { value?: unknown })?.value;
+  if (!Array.isArray(value)) return false;
+
+  return value.some((node) => Array.isArray(node) && node[0] === 'h1');
+}
+
+/**
+ * The prose a generated page OPENS with, flattened to its words.
+ *
+ * The shell draws a page's description under its title, and for a generated
+ * page that was suppressed outright: Content derives a description from the
+ * body where the frontmatter names none, and the body then printed the same
+ * sentence again three lines below.
+ *
+ * Derived and written are indistinguishable once they are in `description`, so
+ * this answers the question that actually matters — does the body already open
+ * with it? A type that writes a real description (an API document's `summary`,
+ * which appears nowhere in its prose) gets the line every written page has; one
+ * whose description was lifted out of its own first paragraph does not.
+ *
+ * Walks INTO the first node, because a generated body opens on a component
+ * call: the prose is that component's children, not a sibling of it.
+ */
+export function generatedLead(body: unknown): string {
+  const value = (body as { value?: unknown })?.value;
+  if (!Array.isArray(value)) return '';
+
+  return collapse(lead(value));
+}
+
+/**
+ * Does the body already open with this description?
+ *
+ * `startsWith` rather than equality, because a page's description is often the
+ * FIRST LINE of prose the page then prints in full — the same sentence at two
+ * lengths, and printing both puts one above the rule and one under it.
+ *
+ * Both sides are collapsed first. Frontmatter folds a wrapped line into a
+ * space; the AST keeps the newline the author typed, so the two spellings of
+ * one sentence differ by exactly the whitespace nobody can see.
+ */
+export function generatedLeadsWith(
+  description: string,
+  body: unknown
+): boolean {
+  const opening = generatedLead(body);
+
+  return Boolean(opening) && opening.startsWith(collapse(description));
+}
+
+/** One sentence, however it was wrapped. */
+const collapse = (value: string) => value.replace(/\s+/g, ' ').trim();
+
+/** The first paragraph's words, however deep the components go. */
+function lead(nodes: unknown[]): string {
+  for (const node of nodes) {
+    if (!Array.isArray(node)) continue;
+
+    const [tag, ...rest] = node as unknown[];
+    if (typeof tag !== 'string') continue;
+
+    if (tag === 'p') return text(node).trim();
+
+    const found = lead(rest.slice(1));
+    if (found) return found;
+  }
+
+  return '';
+}

package/app/utils/heading-link.ts

@@ -0,0 +1,32 @@
+/**
+ * Does this heading's own content already contain a link?
+ *
+ * A Prose heading wraps the WHOLE heading in an anchor, because the words are
+ * what a reader aims at when they want to link to a section. That cannot be
+ * done when the heading is itself a link — `## [1.4.0](…/compare/…)`, which is
+ * what release-please writes on every release, rendered as one page by the
+ * changelog's `flat` granularity. An anchor inside an anchor is invalid HTML:
+ * the parser closes the outer one early, and what is left is a link with no
+ * text in it. `pnpm check:a11y` found it as five `link-name` violations, which
+ * is the honest description — a link a screen reader announces as nothing.
+ *
+ * READ OFF THE VNODES rather than declared by the caller: a heading does not
+ * know what a Markdown file put inside it, and asking is the only way to be
+ * right for content nobody has written yet.
+ *
+ * `href` rather than the tag or the component: MDC renders a link as `ProseA`,
+ * a raw one arrives as `a`, and both carry the prop. Recursive, because a
+ * heading may wrap its link in emphasis.
+ */
+import type { VNode } from 'vue';
+
+export function headingHasLink(nodes: unknown): boolean {
+  if (Array.isArray(nodes)) return nodes.some(headingHasLink);
+  if (!nodes || typeof nodes !== 'object') return false;
+
+  const node = nodes as VNode;
+
+  if (node.props && 'href' in node.props) return true;
+
+  return headingHasLink(node.children);
+}

package/app/utils/locale-path.ts

@@ -0,0 +1,45 @@
+/**
+ * The route path without its locale segment.
+ *
+ * With `prefix_except_default` the browser is on `/de-DE/guide/deploying` while
+ * the documentation page is `/guide/deploying` — the locale translates the
+ * INTERFACE, not the content tree. Every lookup in the theme means the second
+ * one: which collection serves this route, which section is active, which page
+ * to query. Handing them the raw path 404s every page in every non-default
+ * locale, which is exactly what happened the first time this was wired up.
+ *
+ * Pure and separate from the composable so the seam can be tested without a
+ * Nuxt environment, like the source resolver next to it.
+ */
+export function stripLocalePrefix(
+  path: string,
+  codes: Iterable<string>
+): string {
+  return splitLocalePath(path, codes).path;
+}
+
+/**
+ * The same split, keeping the half that was thrown away.
+ *
+ * Which language a URL asks for is not decoration: original and translation
+ * live under IDENTICAL content paths in different collections, so a lookup
+ * given only the stripped path cannot tell them apart and takes whichever
+ * sorted first. Anything choosing a collection needs both halves — see
+ * `sourcesForRoute`.
+ */
+export function splitLocalePath(
+  path: string,
+  codes: Iterable<string>
+): { locale?: string; path: string } {
+  const first = path.split('/')[1];
+  if (!first) return { path };
+
+  for (const code of codes) {
+    if (code !== first) continue;
+
+    const rest = path.slice(first.length + 1);
+    return { locale: code, path: rest.startsWith('/') ? rest : rest || '/' };
+  }
+
+  return { path };
+}