@dogsbay/format-hugo 0.2.0-beta.101

package/dist/nav.js

@@ -0,0 +1,381 @@
+/**
+ * Hugo's implicit navigation, and page identity.
+ *
+ * Every importer so far reads nav from a FILE — `SUMMARY.md`, `mkdocs.yml`,
+ * `sidebars.js`, `docs.json`. Hugo has none. The tree is the directory
+ * structure, and the rules are:
+ *
+ *   content/en/docs/concepts/_index.md   → a SECTION at /docs/concepts/
+ *   content/en/docs/concepts/pods.md     → a page  at /docs/concepts/pods/
+ *   content/en/docs/setup/index.md       → a LEAF BUNDLE (its directory is
+ *                                          the page; images sit beside it)
+ *   weight: 40                           → sort position, ascending
+ *   linkTitle: / title:                  → nav label
+ *   slug: / url:                         → override the URL
+ *
+ * `_index.md` and `index.md` differ by one character and mean opposite things:
+ * the first makes a directory a section with children, the second makes the
+ * directory a single page. Getting that wrong either flattens the tree or
+ * loses every co-located image.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parse as parseToml } from "smol-toml";
+/** Split Hugo frontmatter: `---` YAML, `+++` TOML, or `{ }` JSON. */
+export function splitFrontmatter(source) {
+    const yamlMatch = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(source);
+    if (yamlMatch) {
+        try {
+            return {
+                frontmatter: (parseYaml(yamlMatch[1]) ?? {}),
+                body: source.slice(yamlMatch[0].length),
+            };
+        }
+        catch {
+            return { frontmatter: {}, body: source.slice(yamlMatch[0].length) };
+        }
+    }
+    const tomlMatch = /^\+\+\+\r?\n([\s\S]*?)\r?\n\+\+\+\r?\n?/.exec(source);
+    if (tomlMatch) {
+        try {
+            return {
+                frontmatter: parseToml(tomlMatch[1]),
+                body: source.slice(tomlMatch[0].length),
+            };
+        }
+        catch {
+            return { frontmatter: {}, body: source.slice(tomlMatch[0].length) };
+        }
+    }
+    return { frontmatter: {}, body: source };
+}
+function titleFromSlug(slug) {
+    const last = slug.split("/").filter(Boolean).pop() ?? "";
+    return last
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Directories whose markdown is include-only by convention. Hugo has no formal
+ * marker, but `{{< include "x.md" >}}` resolves here, so these files are
+ * fragments rather than pages.
+ */
+const FRAGMENT_DIRS = ["includes", "included", "_includes", "shortcodes"];
+/**
+ * A page's `menu.main` entry, if it declares one.
+ *
+ * Hugo accepts several shapes: `menu: main`, `menu: [main]`, and
+ * `menu: {main: {weight, title, parent}}`. Only the last carries ordering, but
+ * all three mean "this page is in the main menu".
+ */
+function readMenuMain(fm) {
+    const menu = fm.menu;
+    if (!menu)
+        return {};
+    if (typeof menu === "string" || Array.isArray(menu))
+        return {};
+    const main = menu.main;
+    if (!main || typeof main !== "object")
+        return {};
+    const entry = main;
+    return {
+        weight: typeof entry.weight === "number" ? entry.weight : undefined,
+        title: typeof entry.title === "string" ? entry.title : undefined,
+    };
+}
+/** Whether Hugo would exclude this page from the built site / its lists. */
+function isHidden(fm) {
+    if (fm.draft === true)
+        return true;
+    if (fm.headless === true)
+        return true;
+    const build = fm._build;
+    if (build && (build.render === "never" || build.list === "never"))
+        return true;
+    return false;
+}
+/**
+ * Walk a Hugo content directory into a flat page list.
+ *
+ * Ordinary markdown only — `.html` content pages exist in Hugo but carry no
+ * markdown to import, and pulling them in would emit pages of raw template.
+ */
+/**
+ * Apply a Hugo `[permalinks]` pattern to a page.
+ *
+ * Tokens Hugo defines that matter for docs corpora: `:section`, `:sections`,
+ * `:year`, `:month`, `:day`, `:slug`, `:title`, `:filename`, `:contentbasename`.
+ * An unknown token is left in place rather than silently emitting an empty
+ * segment — a wrong URL you can see beats one you cannot.
+ */
+export function applyPermalink(pattern, ctx) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const d = ctx.date;
+    const values = {
+        section: ctx.section,
+        sections: ctx.sections.join("/"),
+        slug: ctx.slug,
+        title: ctx.title,
+        filename: ctx.filename,
+        contentbasename: ctx.filename,
+        year: d ? String(d.getUTCFullYear()) : "",
+        month: d ? pad(d.getUTCMonth() + 1) : "",
+        day: d ? pad(d.getUTCDate()) : "",
+        monthname: d
+            ? d.toLocaleString("en-US", { month: "long", timeZone: "UTC" })
+            : "",
+    };
+    const out = pattern.replace(/:([a-zA-Z]+)/g, (whole, token) => token in values ? values[token] : whole);
+    return out
+        .split("/")
+        .filter((seg) => seg !== "")
+        .join("/");
+}
+export function collectHugoPages(contentRoot, permalinks = {}, sectionPermalinks = {}) {
+    const pages = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const path = join(dir, name);
+            let stats;
+            try {
+                stats = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (stats.isDirectory()) {
+                walk(path);
+                continue;
+            }
+            const isHtml = name.endsWith(".html") || name.endsWith(".htm");
+            if (!name.endsWith(".md") && !name.endsWith(".markdown") && !isHtml)
+                continue;
+            const rel = relative(contentRoot, path).split("\\").join("/");
+            const source = readFileSync(path, "utf-8");
+            const { frontmatter } = splitFrontmatter(source);
+            const isSection = /^_index\.(md|markdown|html?)$/.test(name);
+            const isLeafBundle = /^index\.(md|markdown|html?)$/.test(name);
+            // The slug is the directory for a bundle/section, the filename otherwise.
+            let slug = rel.replace(/\.(md|markdown|html?)$/, "");
+            if (isSection || isLeafBundle)
+                slug = slug.replace(/\/?(_?index)$/, "");
+            const sections = slug.split("/").slice(0, -1).filter(Boolean);
+            const filename = name.replace(/\.(md|markdown|html?)$/, "");
+            const baseName = isSection || isLeafBundle
+                ? (slug.split("/").pop() ?? filename)
+                : filename;
+            // Hugo lets frontmatter override it. `url:` is absolute; `slug:` renames
+            // only the last segment.
+            const url = typeof frontmatter.url === "string" ? frontmatter.url : undefined;
+            const slugOverride = typeof frontmatter.slug === "string" ? frontmatter.slug : undefined;
+            const topSection = slug.split("/")[0] ?? "";
+            // A SECTION page takes a pattern only from `[permalinks.section]`.
+            // Hugo keeps the two apart and so must we: kubernetes declares only
+            // `[permalinks.page]`, and applying its blog pattern to
+            // `blog/_index.md` rewrote the section's own slug to `blog/blog`,
+            // which dropped "Blog" out of its menu position in the nav.
+            // A page's own `url:` may itself be a PATTERN — 192 kubernetes blog
+            // posts write `url: /:section/:year/:month/:slug/`. Treating it as a
+            // literal path emitted files at `docs/:section/:year/:month/:slug/`,
+            // which is not a URL and which Docusaurus then tried to compile.
+            const patternSource = isSection ? sectionPermalinks : permalinks;
+            const pattern = url && /:[a-zA-Z]/.test(url) ? url : patternSource[topSection];
+            if (url && !/:[a-zA-Z]/.test(url)) {
+                slug = url.replace(/^\/+|\/+$/g, "");
+            }
+            else if (pattern) {
+                // A permalink pattern REPLACES the path-derived slug. This is what
+                // removes `_posts/2018` from a kubernetes blog URL.
+                const rawDate = frontmatter.date;
+                const date = rawDate instanceof Date
+                    ? rawDate
+                    : typeof rawDate === "string" || typeof rawDate === "number"
+                        ? new Date(rawDate)
+                        : undefined;
+                slug = applyPermalink(pattern, {
+                    section: topSection,
+                    sections,
+                    slug: slugOverride ?? baseName,
+                    filename: baseName,
+                    title: typeof frontmatter.title === "string" ? frontmatter.title : baseName,
+                    date: date && !Number.isNaN(date.getTime()) ? date : undefined,
+                });
+            }
+            else if (slugOverride) {
+                const parts = slug.split("/");
+                parts[parts.length - 1] = slugOverride;
+                slug = parts.join("/");
+            }
+            slug = slug.replace(/^\/+|\/+$/g, "");
+            const title = (typeof frontmatter.title === "string" && frontmatter.title) ||
+                titleFromSlug(slug || "home");
+            // Hugo's MENU system is a second, independent source of both the nav
+            // label and the ordering: kubernetes gives `docs` no top-level `weight`
+            // at all and writes `menu: {main: {weight: 10}}` instead. Reading only
+            // `weight` put every top-level section in the unweighted bucket, so they
+            // sorted alphabetically and "Blog" landed above "Documentation".
+            const menuMain = readMenuMain(frontmatter);
+            const linkTitle = (typeof frontmatter.linkTitle === "string" && frontmatter.linkTitle) ||
+                (typeof frontmatter.linktitle === "string" && frontmatter.linktitle) ||
+                menuMain.title ||
+                title;
+            pages.push({
+                file: path,
+                rel,
+                slug,
+                title,
+                linkTitle,
+                weight: typeof frontmatter.weight === "number"
+                    ? frontmatter.weight
+                    : menuMain.weight,
+                frontmatter,
+                isSection,
+                isLeafBundle,
+                unrenderable: isHtml,
+                hidden: isHidden(frontmatter),
+                fragment: FRAGMENT_DIRS.some((d) => rel === `${d}` || rel.startsWith(`${d}/`)),
+            });
+        }
+    };
+    walk(contentRoot);
+    return pages;
+}
+/**
+ * Build the nav tree from the page set.
+ *
+ * Ordering is Hugo's: `weight` ascending, then title. Pages with no weight
+ * sort AFTER weighted ones — Hugo treats a missing weight as 0 and then falls
+ * back to date/title, but for docs the practical rule authors rely on is
+ * "weighted items lead, the rest follow alphabetically".
+ */
+export function buildHugoNav(pages, hrefPrefix = "") {
+    const visible = pages.filter((p) => !p.hidden && !p.fragment);
+    const bySlug = new Map();
+    for (const p of visible)
+        bySlug.set(p.slug, p);
+    const href = (slug) => `${hrefPrefix}/${slug}`.replace(/\/{2,}/g, "/");
+    // EVERY directory is a section in Hugo — `_index.md` only lets you give one
+    // front matter. Recursing solely into pages that have an `_index.md` lost
+    // 1,479 of 2,445 pages, because a directory like `blog/_posts/2022/` has no
+    // index file and its children were therefore never reached. So the tree is
+    // built from the SLUG PATHS, and a directory with no page of its own becomes
+    // a label-only node.
+    const childSlugs = new Map();
+    const register = (parent, child) => {
+        const set = childSlugs.get(parent) ?? new Set();
+        set.add(child);
+        childSlugs.set(parent, set);
+    };
+    for (const page of visible) {
+        if (page.slug === "")
+            continue;
+        const parts = page.slug.split("/");
+        for (let i = 0; i < parts.length; i++) {
+            const child = parts.slice(0, i + 1).join("/");
+            const parent = i === 0 ? "" : parts.slice(0, i).join("/");
+            register(parent, child);
+        }
+    }
+    const sortKey = (slug) => {
+        const page = bySlug.get(slug);
+        const label = page?.linkTitle ?? titleFromSlug(slug);
+        // Weighted items lead, unweighted follow alphabetically — the rule docs
+        // authors actually rely on.
+        return [page?.weight === undefined ? 1 : 0, page?.weight ?? 0, label];
+    };
+    const build = (parent, depth) => {
+        if (depth > 12)
+            return [];
+        const slugs = [...(childSlugs.get(parent) ?? [])].sort((a, b) => {
+            const [ag, aw, al] = sortKey(a);
+            const [bg, bw, bl] = sortKey(b);
+            return ag - bg || aw - bw || al.localeCompare(bl);
+        });
+        return slugs.map((slug) => {
+            const page = bySlug.get(slug);
+            const kids = build(slug, depth + 1);
+            const item = { label: page?.linkTitle ?? titleFromSlug(slug) };
+            // A directory with no page of its own is a label only — giving it an
+            // href would produce a nav entry that 404s.
+            if (page)
+                item.href = href(slug);
+            if (kids.length > 0)
+                item.children = kids;
+            return item;
+        });
+    };
+    return build("", 0);
+}
+/**
+ * Resolve a `{{< ref >}}` / `{{< relref >}}` target against the page set.
+ *
+ * 2,570 calls in the kubernetes corpus — the most common shortcode by a wide
+ * margin, and every unresolved one is a broken link. Hugo accepts a lot of
+ * forms for the same page:
+ *
+ *   "/docs/concepts/_index.md"   root-relative with the file name
+ *   "docs/concepts"              root-relative, no extension
+ *   "pods.md"                    relative to the calling page
+ *   "#anchor" / "page.md#anchor" with a fragment
+ */
+export function makeRefResolver(pages, hrefPrefix = "") {
+    const bySlug = new Map();
+    const byRel = new Map();
+    const byBasename = new Map();
+    for (const page of pages) {
+        bySlug.set(page.slug, page);
+        byRel.set(page.rel, page);
+        byRel.set(page.rel.replace(/\.(md|markdown)$/, ""), page);
+        const base = page.rel.split("/").pop().replace(/\.(md|markdown)$/, "");
+        const list = byBasename.get(base) ?? [];
+        list.push(page);
+        byBasename.set(base, list);
+    }
+    const href = (page, fragment) => `${hrefPrefix}/${page.slug}${fragment}`.replace(/\/{2,}/g, "/");
+    return (target, from) => {
+        if (!target)
+            return undefined;
+        // A bare fragment stays on the page.
+        if (target.startsWith("#"))
+            return target;
+        const hashAt = target.indexOf("#");
+        const fragment = hashAt === -1 ? "" : target.slice(hashAt);
+        let path = (hashAt === -1 ? target : target.slice(0, hashAt)).trim();
+        path = path.replace(/^\/+/, "").replace(/\/+$/, "");
+        const noExt = path.replace(/\.(md|markdown)$/, "").replace(/\/?_?index$/, "");
+        // Root-relative, by slug or by source path.
+        for (const key of [noExt, path]) {
+            const hit = bySlug.get(key) ?? byRel.get(key);
+            if (hit)
+                return href(hit, fragment);
+        }
+        // Relative to the calling page's directory.
+        if (from) {
+            const dir = from.split("/").slice(0, -1).join("/");
+            const joined = [dir, path].filter(Boolean).join("/");
+            const joinedNoExt = joined.replace(/\.(md|markdown)$/, "").replace(/\/?_?index$/, "");
+            const hit = byRel.get(joined) ?? byRel.get(joinedNoExt) ?? bySlug.get(joinedNoExt);
+            if (hit)
+                return href(hit, fragment);
+        }
+        // Last resort: a unique basename match. Hugo itself does this, and it is
+        // how `{{< ref "pods.md" >}}` works from anywhere in the tree. Ambiguous
+        // names are NOT guessed — the caller records the failure instead.
+        const base = noExt.split("/").pop() ?? "";
+        const candidates = byBasename.get(base);
+        if (candidates && candidates.length === 1)
+            return href(candidates[0], fragment);
+        return undefined;
+    };
+}
+//# sourceMappingURL=nav.js.map

package/dist/nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.js","sourceRoot":"","sources":["../src/nav.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shortcode mapping registry.
+ *
+ * Hugo has no fixed shortcode vocabulary: a site defines its own in
+ * `layouts/shortcodes/`, and a theme ships more. Kubernetes uses 52 distinct
+ * names, of which only a handful are Hugo builtins. So the registry is OPEN,
+ * in three layers — builtins < theme (docsy) < site (kubernetes) < user —
+ * exactly like the MDX adapters, because a site-specific shortcode must never
+ * become a core concern.
+ *
+ * A shortcode with no mapping is NEVER dropped: it is preserved verbatim and
+ * recorded in the fidelity ledger, so an unmapped construct is a known loss
+ * rather than a silent one.
+ */
+import type { ShortcodeArgs, ShortcodeNode } from "./shortcodes.js";
+import type { HugoConfig } from "./config.js";
+export interface ShortcodeContext {
+    /** Translate a Hugo source fragment (a shortcode body) to Dogsbay-MD. */
+    translate: (source: string) => string;
+    /** Site config — params, baseURL, languages. */
+    config: HugoConfig;
+    /** Record a fidelity note. */
+    report: (entry: Omit<HugoLedgerEntry, "file">) => void;
+    /** Resolve a `{{< ref >}}`-style page reference to an href, if possible. */
+    resolveRef?: (target: string, from?: string) => string | undefined;
+    /**
+     * Read a file a shortcode references. The SECOND argument is the calling
+     * page: `{{< include "included/x.md" >}}` resolves beside the page, while
+     * `{{< include "task-tutorial-prereqs.md" >}}` resolves in the site's
+     * conventional `includes/` directory — so the resolver needs both.
+     */
+    readContentFile?: (path: string, fromFile?: string) => string | undefined;
+    /** Source file currently being translated, relative to the content root. */
+    file?: string;
+}
+export interface HugoLedgerEntry {
+    /** Shortcode name. */
+    shortcode: string;
+    /**
+     * What happened:
+     * - "preserved" — kept verbatim (unmapped);
+     * - "stripped"  — deliberately dropped by a mapping;
+     * - "degraded"  — mapped, but something about it could not be carried.
+     */
+    action: "preserved" | "stripped" | "degraded";
+    /** Why, in one line. */
+    note?: string;
+    /** 1-based line in the source. */
+    line: number;
+    file?: string;
+}
+/**
+ * Turn a shortcode into Dogsbay-MD source.
+ *
+ * Return `null` to drop it (recorded as "stripped"), or `undefined` to fall
+ * through to preservation (recorded as "preserved"). Returning a string means
+ * the mapping owns the output.
+ */
+export type ShortcodeMapping = (node: ShortcodeNode, ctx: ShortcodeContext) => string | null | undefined;
+export type ShortcodeRegistry = Record<string, ShortcodeMapping>;
+/** First positional argument, or a named one, whichever the call used. */
+export declare function arg(args: ShortcodeArgs, ...names: string[]): string | undefined;
+/** `{key="value"}` attribute block for a Dogsbay-MD directive, or "". */
+export declare function attrBlock(attrs: Record<string, string | undefined>): string;
+/**
+ * Emit a `:::` block directive whose fence is longer than any fence inside it.
+ *
+ * Hugo shortcodes nest arbitrarily (`tabs > tab > note`), and Dogsbay-MD
+ * closes at the first bare `:::`, so a fixed three-colon fence would let an
+ * inner directive terminate its own parent and spill the rest of the tab into
+ * the page.
+ */
+export declare function directive(name: string, attrs: string, body: string): string;
+/**
+ * Merge registry layers. Later layers win, which is what lets a site override
+ * a theme's shortcode of the same name.
+ */
+export declare function composeRegistry(...layers: ShortcodeRegistry[]): ShortcodeRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,gDAAgD;IAChD,MAAM,EAAE,UAAU,CAAC;IACnB,8BAA8B;IAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;IACvD,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1E,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9C,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,gBAAgB,KAClB,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/B,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEjE,0EAA0E;AAC1E,wBAAgB,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAK/E;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAQ3E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,MAAM,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,CAEjF"}

package/dist/registry.js

@@ -0,0 +1,41 @@
+/** First positional argument, or a named one, whichever the call used. */
+export function arg(args, ...names) {
+    for (const name of names) {
+        if (args.named[name] !== undefined)
+            return args.named[name];
+    }
+    return args.positional[0];
+}
+/** `{key="value"}` attribute block for a Dogsbay-MD directive, or "". */
+export function attrBlock(attrs) {
+    const entries = Object.entries(attrs).filter((e) => e[1] !== undefined && e[1] !== "");
+    if (entries.length === 0)
+        return "";
+    return `{${entries
+        .map(([k, v]) => `${k}="${v.replace(/"/g, """)}"`)
+        .join(" ")}}`;
+}
+/**
+ * Emit a `:::` block directive whose fence is longer than any fence inside it.
+ *
+ * Hugo shortcodes nest arbitrarily (`tabs > tab > note`), and Dogsbay-MD
+ * closes at the first bare `:::`, so a fixed three-colon fence would let an
+ * inner directive terminate its own parent and spill the rest of the tab into
+ * the page.
+ */
+export function directive(name, attrs, body) {
+    const inner = Math.max(0, ...[...body.matchAll(/^(:{3,})/gm)].map((m) => m[1].length));
+    const fence = ":".repeat(Math.max(3, inner + 1));
+    const trimmed = body.replace(/^\n+|\n+$/g, "");
+    return trimmed
+        ? `${fence}${name}${attrs}\n${trimmed}\n${fence}`
+        : `${fence}${name}${attrs}\n${fence}`;
+}
+/**
+ * Merge registry layers. Later layers win, which is what lets a site override
+ * a theme's shortcode of the same name.
+ */
+export function composeRegistry(...layers) {
+    return Object.assign({}, ...layers);
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAoEA,0EAA0E;AAC1E,MAAM,UAAU,GAAG,CAAC,IAAmB,EAAE,GAAG,KAAe;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,KAAyC;IACjE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAC1C,CAAC,CAAC,EAAyB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAChE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,OAAO,IAAI,OAAO;SACf,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;SACtD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,KAAa,EACb,IAAY;IAEZ,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,EACD,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAC5D,CAAC;IACF,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,OAAO;QACZ,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,KAAK,OAAO,KAAK,KAAK,EAAE;QACjD,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,KAAK,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAG,MAA2B;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,MAAM,CAAsB,CAAC;AAC3D,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,26 @@
+export interface ContentResolverOptions {
+    /** Absolute path of the language content root, e.g. `<site>/content/en`. */
+    contentRoot: string;
+    /**
+     * Directories to try, relative to the content root, in order. The default
+     * covers Hugo's conventional `includes/` plus the `examples/` tree
+     * `code_sample` reads from.
+     */
+    searchDirs?: string[];
+}
+/**
+ * Build a reader that takes a shortcode's file argument and the page it was
+ * called from, and returns the file's text — or undefined, so the caller
+ * records an unresolved reference rather than emitting nothing silently.
+ */
+export declare function makeContentResolver(opts: ContentResolverOptions): (path: string, fromFile?: string) => string | undefined;
+/**
+ * Whether a shortcode's `include=` argument names a FILE.
+ *
+ * It does not always: `{{< feature-gate-table include="alpha,beta" >}}` uses
+ * the same attribute name as a filter. Treating that as a path produced a
+ * guaranteed-failing read and a misleading "could not read included file"
+ * ledger entry on every one of them.
+ */
+export declare function looksLikeFile(value: string | undefined): boolean;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,sBAAsB,GAC3B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CA6CzD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEhE"}

package/dist/resolve.js

@@ -0,0 +1,81 @@
+/**
+ * File resolution for `{{< include >}}`, `{{< code_sample >}}` and
+ * `{{< tab include= >}}`.
+ *
+ * Hugo shortcodes reference files by a site convention, not by a path the
+ * caller can use directly. Measured on kubernetes/website:
+ *
+ *   {{< include "task-tutorial-prereqs.md" >}}     → content/en/includes/…   (131×)
+ *   {{< include "included/verify-kubectl.md" >}}   → beside the page          (9×)
+ *   {{< code_sample file="pods/simple.yaml" >}}    → content/en/examples/…
+ *   {{< tab include="generated/x.md" />}}          → beside the page
+ *
+ * Resolving only one of those left 171 of 171 includes and 106 tabs empty,
+ * each with a ledger entry — honest, but the content was right there.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+/**
+ * Build a reader that takes a shortcode's file argument and the page it was
+ * called from, and returns the file's text — or undefined, so the caller
+ * records an unresolved reference rather than emitting nothing silently.
+ */
+export function makeContentResolver(opts) {
+    const { contentRoot } = opts;
+    const searchDirs = opts.searchDirs ?? ["includes", "examples", "static", "."];
+    return (path, fromFile) => {
+        if (!path)
+            return undefined;
+        // Reject `..` outright. Hugo shortcode file arguments are never legitimately
+        // parent-relative, and allowing them let a path escape the search
+        // directories entirely: `../secret.txt` resolved against `includes/`
+        // reaches the content root, and the startsWith guard below does not catch
+        // that because the result is still inside the root.
+        if (path.split(/[\\/]/).some((seg) => seg === ".."))
+            return undefined;
+        const clean = path.replace(/^\.\//, "");
+        const candidates = [];
+        // Page-relative first: `included/verify-kubectl.md` sits beside the page.
+        if (fromFile) {
+            const pageDir = isAbsolute(fromFile)
+                ? dirname(fromFile)
+                : resolve(contentRoot, dirname(fromFile));
+            candidates.push(resolve(pageDir, clean));
+        }
+        // Then the site conventions.
+        for (const dir of searchDirs) {
+            candidates.push(resolve(contentRoot, dir, clean.replace(/^\//, "")));
+        }
+        // Finally, root-relative.
+        candidates.push(resolve(contentRoot, clean.replace(/^\//, "")));
+        for (const candidate of candidates) {
+            // Never escape the content root: a shortcode argument is site data, and
+            // `../../etc/passwd` must not be readable through it.
+            // `startsWith` alone would admit a sibling directory whose name shares
+            // the prefix (`/content/en-old` for a root of `/content/en`).
+            if (candidate !== contentRoot && !candidate.startsWith(contentRoot + sep))
+                continue;
+            try {
+                if (existsSync(candidate) && statSync(candidate).isFile()) {
+                    return readFileSync(candidate, "utf-8");
+                }
+            }
+            catch {
+                // Unreadable — keep trying the remaining candidates.
+            }
+        }
+        return undefined;
+    };
+}
+/**
+ * Whether a shortcode's `include=` argument names a FILE.
+ *
+ * It does not always: `{{< feature-gate-table include="alpha,beta" >}}` uses
+ * the same attribute name as a filter. Treating that as a path produced a
+ * guaranteed-failing read and a misleading "could not read included file"
+ * ledger entry on every one of them.
+ */
+export function looksLikeFile(value) {
+    return typeof value === "string" && /\.[A-Za-z0-9]{1,6}$/.test(value.trim());
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAa9D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA4B;IAE5B,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE9E,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE;QACxB,IAAI,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QAC5B,6EAA6E;QAC7E,kEAAkE;QAClE,qEAAqE;QACrE,0EAA0E;QAC1E,oDAAoD;QACpD,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC;YAAE,OAAO,SAAS,CAAC;QACtE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACxC,MAAM,UAAU,GAAa,EAAE,CAAC;QAEhC,0EAA0E;QAC1E,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC;gBAClC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACnB,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC5C,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,6BAA6B;QAC7B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,0BAA0B;QAC1B,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAEhE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,wEAAwE;YACxE,sDAAsD;YACtD,uEAAuE;YACvE,8DAA8D;YAC9D,IAAI,SAAS,KAAK,WAAW,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC;gBAAE,SAAS;YACpF,IAAI,CAAC;gBACH,IAAI,UAAU,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;oBAC1D,OAAO,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,qDAAqD;YACvD,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/E,CAAC"}