@dogsbay/format-hugo 0.2.0-beta.101

package/dist/shortcodes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Hugo shortcode scanner.
+ *
+ * Hugo content is markdown PLUS a template language, and the template has two
+ * delimiter forms with different evaluation semantics:
+ *
+ *   {{< sc >}}          output inserted RAW — not markdown-processed
+ *   {{% sc %}}          inner content IS markdown-processed
+ *   {{< sc >}}…{{< /sc >}}   paired (has a body)
+ *   {{< sc "pos" k="v" >}}   positional AND named arguments, in one call
+ *
+ * A regex sweep cannot read this. Shortcodes nest (`tabs` contains `tab`
+ * contains `note`), the two delimiter forms mix freely INSIDE one another
+ * (k8s writes `{{< tabs >}}{{% tab %}}`), and a shortcode inside a fenced code
+ * block is literal text that must survive byte-exact — the Hugo docs
+ * themselves are full of those.
+ *
+ * So this is a scanner: it walks the source once, tracks fences, and returns
+ * spans with their nesting resolved.
+ */
+export type ShortcodeDelimiter = "angle" | "percent";
+export interface ShortcodeArgs {
+    /** Positional arguments, in order: `{{< youtube dQw4w9WgXcQ >}}`. */
+    positional: string[];
+    /** Named arguments: `{{< tabs name="x" >}}`. */
+    named: Record<string, string>;
+}
+export interface ShortcodeNode {
+    kind: "shortcode";
+    name: string;
+    args: ShortcodeArgs;
+    delimiter: ShortcodeDelimiter;
+    /** Inner source between the open and close tags; "" when self-closing. */
+    inner: string;
+    /** Verbatim source span, open tag through close tag. */
+    raw: string;
+    /** True when the shortcode had no closing tag. */
+    selfClosing: boolean;
+    /** 1-based line of the opening tag. */
+    line: number;
+}
+export interface TextNode {
+    kind: "text";
+    text: string;
+}
+export type ScanNode = ShortcodeNode | TextNode;
+/** Parse the argument string of a shortcode call. */
+export declare function parseArgs(text: string): ShortcodeArgs;
+/**
+ * Split source into alternating text and shortcode nodes, at the TOP level.
+ * A paired shortcode's body stays in `inner` for the caller to scan
+ * recursively — that is what makes nesting work without a second parser.
+ */
+export declare function scanShortcodes(source: string): ScanNode[];
+/**
+ * Hugo's content-type body markers.
+ *
+ * Kubernetes pages carry `<!-- overview -->`, `<!-- body -->`, `<!-- steps -->`
+ * HTML comments that the Docsy/k8s templates use to slot content into a page
+ * layout. They are STRUCTURAL, not decorative: left in place they render as
+ * stray comments, and a serializer that treats them as raw HTML forces the
+ * page into a JSX dialect for no reason.
+ */
+export declare const CONTENT_TYPE_MARKERS: string[];
+export declare function stripContentTypeMarkers(source: string): string;
+//# sourceMappingURL=shortcodes.d.ts.map

package/dist/shortcodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcodes.d.ts","sourceRoot":"","sources":["../src/shortcodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,QAAQ,CAAC;AAuDhD,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAwBrD;AA0CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAyDzD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,UAWhC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9D"}

package/dist/shortcodes.js

@@ -0,0 +1,216 @@
+/**
+ * Hugo shortcode scanner.
+ *
+ * Hugo content is markdown PLUS a template language, and the template has two
+ * delimiter forms with different evaluation semantics:
+ *
+ *   {{< sc >}}          output inserted RAW — not markdown-processed
+ *   {{% sc %}}          inner content IS markdown-processed
+ *   {{< sc >}}…{{< /sc >}}   paired (has a body)
+ *   {{< sc "pos" k="v" >}}   positional AND named arguments, in one call
+ *
+ * A regex sweep cannot read this. Shortcodes nest (`tabs` contains `tab`
+ * contains `note`), the two delimiter forms mix freely INSIDE one another
+ * (k8s writes `{{< tabs >}}{{% tab %}}`), and a shortcode inside a fenced code
+ * block is literal text that must survive byte-exact — the Hugo docs
+ * themselves are full of those.
+ *
+ * So this is a scanner: it walks the source once, tracks fences, and returns
+ * spans with their nesting resolved.
+ */
+/**
+ * Byte ranges that are LITERAL: fenced code blocks and inline code spans.
+ * A shortcode inside them is documentation about shortcodes, not a call.
+ */
+function literalRanges(source) {
+    const ranges = [];
+    const lines = source.split("\n");
+    let offset = 0;
+    let fence = null;
+    for (const line of lines) {
+        const lineStart = offset;
+        offset += line.length + 1;
+        const trimmed = line.trim();
+        if (!fence) {
+            const open = /^(`{3,}|~{3,})/.exec(trimmed);
+            if (open) {
+                fence = { marker: open[1], start: lineStart };
+                continue;
+            }
+            // Inline code spans on a non-fence line.
+            for (const m of line.matchAll(/`+[^`]*`+/g)) {
+                ranges.push([lineStart + m.index, lineStart + m.index + m[0].length]);
+            }
+        }
+        else {
+            // CommonMark: the closer is the same character, at least as long, and
+            // carries no info string.
+            const close = new RegExp(`^${fence.marker[0]}{${fence.marker.length},}[ \\t]*$`);
+            if (close.test(trimmed)) {
+                ranges.push([fence.start, offset]);
+                fence = null;
+            }
+        }
+    }
+    // An unterminated fence still protects everything to end of file: its
+    // content is code either way, and editing it is the worse failure.
+    if (fence)
+        ranges.push([fence.start, source.length]);
+    return ranges;
+}
+/** Parse the argument string of a shortcode call. */
+export function parseArgs(text) {
+    const positional = [];
+    const named = {};
+    // Named first: `k="v"`, `k='v'`, `k=bare`. Then whatever is left is
+    // positional. Quoted positional args keep their spaces.
+    const consumed = [];
+    for (const m of text.matchAll(/([A-Za-z_][\w.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))/g)) {
+        named[m[1]] = m[2] ?? m[3] ?? m[4] ?? "";
+        consumed.push([m.index, m.index + m[0].length]);
+    }
+    let rest = "";
+    let cursor = 0;
+    for (const [s, e] of consumed) {
+        rest += text.slice(cursor, s);
+        cursor = e;
+    }
+    rest += text.slice(cursor);
+    for (const m of rest.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+        const value = m[1] ?? m[2] ?? m[3];
+        if (value !== undefined && value !== "")
+            positional.push(value);
+    }
+    return { positional, named };
+}
+/** Every shortcode tag in the source, skipping literal ranges. */
+function findTags(source) {
+    const literals = literalRanges(source);
+    const inLiteral = (i) => literals.some(([s, e]) => i >= s && i < e);
+    const tags = [];
+    // `{{<` or `{{%`, optional `/`, name, args, matching close delimiter.
+    // The args run is lazy and skips quoted regions so a `>` or `%` inside a
+    // quoted value cannot terminate the tag early.
+    // Note the `\s*` on BOTH sides of the optional slash. Hugo accepts
+    // `{{< /note >}}` and `{{</ note >}}` alike, and the kubernetes corpus uses
+    // the second form for 160 of its closers — requiring the name to follow the
+    // slash immediately left every one of those shortcodes unpaired, which would
+    // have swallowed each mermaid diagram's body as loose text.
+    const re = /\{\{([<%])(-?)\s*(\/?)\s*([A-Za-z_][\w./-]*)((?:[^"'>%]|"[^"]*"|'[^']*')*?)(-?)\s*([>%])\}\}/g;
+    for (const m of source.matchAll(re)) {
+        const open = m[1];
+        const close = m[7];
+        // `{{< … >}}` and `{{% … %}}` — the delimiters must agree.
+        if ((open === "<" && close !== ">") || (open === "%" && close !== "%"))
+            continue;
+        if (inLiteral(m.index))
+            continue;
+        // `{{< tab name="x" include="y" />}}` — Hugo's explicit self-close. The
+        // kubeadm reference pages use it 118 times. Without recognising it, the
+        // tag looks like an opener with no closer, so a LATER `{{< /tab >}}` from
+        // a different group could be paired to it and swallow everything between.
+        const rawArgs = (m[5] ?? "").replace(/\s*\/\s*$/, "");
+        tags.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            name: m[4],
+            closing: m[3] === "/",
+            explicitSelfClose: /\/\s*$/.test(m[5] ?? ""),
+            delimiter: open === "<" ? "angle" : "percent",
+            args: parseArgs(rawArgs),
+            line: source.slice(0, m.index).split("\n").length,
+        });
+    }
+    return tags;
+}
+/**
+ * Split source into alternating text and shortcode nodes, at the TOP level.
+ * A paired shortcode's body stays in `inner` for the caller to scan
+ * recursively — that is what makes nesting work without a second parser.
+ */
+export function scanShortcodes(source) {
+    const tags = findTags(source);
+    const out = [];
+    let cursor = 0;
+    for (let i = 0; i < tags.length; i++) {
+        const tag = tags[i];
+        if (tag.start < cursor)
+            continue; // already consumed inside a pair
+        if (tag.closing)
+            continue; // orphan closer — treated as text below
+        // Find the matching closer, counting nested opens of the SAME name.
+        // An explicitly self-closed tag has no body and must not consume one.
+        let closer;
+        if (!tag.explicitSelfClose) {
+            let depth = 1;
+            for (let j = i + 1; j < tags.length; j++) {
+                if (tags[j].name !== tag.name)
+                    continue;
+                if (tags[j].explicitSelfClose)
+                    continue;
+                depth += tags[j].closing ? -1 : 1;
+                if (depth === 0) {
+                    closer = tags[j];
+                    break;
+                }
+            }
+        }
+        if (tag.start > cursor)
+            out.push({ kind: "text", text: source.slice(cursor, tag.start) });
+        if (closer) {
+            out.push({
+                kind: "shortcode",
+                name: tag.name,
+                args: tag.args,
+                delimiter: tag.delimiter,
+                inner: source.slice(tag.end, closer.start),
+                raw: source.slice(tag.start, closer.end),
+                selfClosing: false,
+                line: tag.line,
+            });
+            cursor = closer.end;
+        }
+        else {
+            out.push({
+                kind: "shortcode",
+                name: tag.name,
+                args: tag.args,
+                delimiter: tag.delimiter,
+                inner: "",
+                raw: source.slice(tag.start, tag.end),
+                selfClosing: true,
+                line: tag.line,
+            });
+            cursor = tag.end;
+        }
+    }
+    if (cursor < source.length)
+        out.push({ kind: "text", text: source.slice(cursor) });
+    return out;
+}
+/**
+ * Hugo's content-type body markers.
+ *
+ * Kubernetes pages carry `<!-- overview -->`, `<!-- body -->`, `<!-- steps -->`
+ * HTML comments that the Docsy/k8s templates use to slot content into a page
+ * layout. They are STRUCTURAL, not decorative: left in place they render as
+ * stray comments, and a serializer that treats them as raw HTML forces the
+ * page into a JSX dialect for no reason.
+ */
+export const CONTENT_TYPE_MARKERS = [
+    "overview",
+    "body",
+    "steps",
+    "prerequisites",
+    "objectives",
+    "lessoncontent",
+    "whatsnext",
+    "cleanup",
+    "discussion",
+    "editorschoice",
+];
+export function stripContentTypeMarkers(source) {
+    const names = CONTENT_TYPE_MARKERS.join("|");
+    return source.replace(new RegExp(`^[ \\t]*<!--\\s*(?:${names})\\s*-->[ \\t]*$\\n?`, "gim"), "");
+}
+//# sourceMappingURL=shortcodes.js.map

package/dist/shortcodes.js.map

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

package/dist/translate.d.ts

@@ -0,0 +1,19 @@
+import { type HugoLedgerEntry, type ShortcodeRegistry } from "./registry.js";
+import type { HugoConfig } from "./config.js";
+export interface TranslateOptions {
+    config: HugoConfig;
+    /** Extra/overriding shortcode mappings, merged last. */
+    shortcodes?: ShortcodeRegistry;
+    /** Include the Kubernetes site layer. Auto-enabled when the site looks like k8s. */
+    kubernetes?: boolean;
+    resolveRef?: (target: string, from?: string) => string | undefined;
+    readContentFile?: (path: string, fromFile?: string) => string | undefined;
+    /** Source file, relative to the content root — stamped onto ledger entries. */
+    file?: string;
+}
+export interface TranslateResult {
+    markdown: string;
+    ledger: HugoLedgerEntry[];
+}
+export declare function translateHugo(source: string, opts: TranslateOptions): TranslateResult;
+//# sourceMappingURL=translate.d.ts.map

package/dist/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"AAYA,OAAO,EAA0C,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGrH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,oFAAoF;IACpF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1E,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,eAAe,CA8DrF"}

package/dist/translate.js

@@ -0,0 +1,99 @@
+/**
+ * Hugo source → Dogsbay-MD.
+ *
+ * Translate-then-parse, the approach format-gitbook and format-myst use: turn
+ * the Hugo dialect into Dogsbay-MD and hand it to the existing parser, rather
+ * than writing a second markdown parser that will drift from the first.
+ *
+ * The never-drop rule: a shortcode with no mapping is emitted VERBATIM and
+ * recorded. A migration that silently deletes what it does not understand is
+ * worse than one that leaves a visible marker.
+ */
+import { scanShortcodes, stripContentTypeMarkers } from "./shortcodes.js";
+import { composeRegistry } from "./registry.js";
+import { BUILTIN_SHORTCODES } from "./builtins.js";
+import { KUBERNETES_SHORTCODES } from "./kubernetes.js";
+/** Depth cap: an include cycle must not recurse forever. */
+const MAX_DEPTH = 8;
+export function translateHugo(source, opts) {
+    const ledger = [];
+    const registry = composeRegistry(BUILTIN_SHORTCODES, opts.kubernetes === false ? {} : KUBERNETES_SHORTCODES, opts.shortcodes ?? {});
+    const report = (entry) => {
+        ledger.push({ ...entry, file: opts.file });
+    };
+    const translate = (text, depth) => {
+        if (depth > MAX_DEPTH)
+            return text;
+        const ctx = {
+            translate: (inner) => translate(inner, depth + 1),
+            config: opts.config,
+            report,
+            resolveRef: opts.resolveRef,
+            readContentFile: (path, from) => opts.readContentFile?.(path, from ?? opts.file),
+            file: opts.file,
+        };
+        let out = "";
+        for (const node of scanShortcodes(text)) {
+            if (node.kind === "text") {
+                out += node.text;
+                continue;
+            }
+            const mapping = registry[node.name];
+            if (!mapping) {
+                // NEVER drop. Preserve verbatim + record.
+                report({
+                    shortcode: node.name,
+                    action: "preserved",
+                    note: "no mapping — kept verbatim",
+                    line: node.line,
+                });
+                out += node.raw;
+                continue;
+            }
+            const result = mapping(node, ctx);
+            if (result === null)
+                continue; // deliberate drop; the mapping recorded it
+            if (result === undefined) {
+                report({
+                    shortcode: node.name,
+                    action: "preserved",
+                    note: "mapping declined — kept verbatim",
+                    line: node.line,
+                });
+                out += node.raw;
+                continue;
+            }
+            out += result;
+        }
+        return out;
+    };
+    // Body markers are structural template slots, not content: left in place
+    // they render as stray comments and push the page into a raw-HTML path.
+    const cleaned = stripContentTypeMarkers(source);
+    const markdown = tidy(translate(cleaned, 0));
+    return { markdown, ledger };
+}
+/**
+ * A block directive must start its own line, and Dogsbay-MD closes a `:::`
+ * block at a line that is only colons. A shortcode written inline
+ * (`text {{< note >}}…{{< /note >}}`) would otherwise emit `text :::note`,
+ * which is a paragraph containing colons rather than a callout.
+ */
+function tidy(markdown) {
+    return (markdown
+        // An OPENER is a colon run followed by a directive name, so it must
+        // begin its own line.
+        // `[^\n:]` — NOT `[^\n]`. A nested group uses a longer fence
+        // (`::::tabs` around `:::tab`), and a class that admits `:` matched the
+        // run's own first colon, splitting `::::tabs` into `:` + `:::tabs` and
+        // leaving a stray colon in the page.
+        .replace(/([^\n:])\n?(:{3,}[A-Za-z])/g, "$1\n\n$2")
+        // A CLOSER is a colon run NOT followed by a name. Only break after it
+        // when text follows on the same line — the negative lookahead is what
+        // keeps this rule from splitting `:::note` into `:::` + `note`, which
+        // is exactly what a naive version of this function did.
+        .replace(/(^|\n)(:{3,})(?![A-Za-z{:])[ \t]*([^\s:][^\n]*)/g, "$1$2\n\n$3")
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/[ \t]+$/gm, ""));
+}
+//# sourceMappingURL=translate.js.map

package/dist/translate.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dogsbay/format-hugo",
+  "version": "0.2.0-beta.101",
+  "description": "Hugo format plugin for Dogsbay — imports Hugo/Docsy sites into TreeNode[] by scanning shortcodes and translating them to Dogsbay-MD.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "smol-toml": "^1.4.2",
+    "yaml": "^2.9.0",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.101",
+    "@dogsbay/types": "0.2.0-beta.101"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}