@dogsbay/format-starlight 0.2.0-beta.0

package/dist/cli.js

@@ -0,0 +1,231 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { parseMeta } from "@dogsbay/types";
+import { starlightToTree as starlightToTreeLegacy, extractFrontmatter } from "./parse.js";
+import { starlightToTree as starlightToTreeMdx } from "./parse-mdx.js";
+import { cloudflareAdapter } from "./adapters/cloudflare.js";
+import { buildNavFromDirectory, buildNavFromConfig } from "./nav.js";
+const ADAPTERS = {
+    cloudflare: cloudflareAdapter,
+};
+/**
+ * Detect if a directory contains a Starlight docs source.
+ *
+ * Checks for:
+ * 1. src/content/docs/ directory with .mdx files
+ * 2. astro.config with @astrojs/starlight
+ * 3. .mdx files with Starlight-style frontmatter (sidebar.order)
+ */
+function detectStarlightSource(path) {
+    // Check for src/content/docs/ pattern
+    const docsDir = join(path, "src", "content", "docs");
+    if (existsSync(docsDir)) {
+        const entries = readdirSync(docsDir, { recursive: true });
+        if (entries.some((e) => e.endsWith(".mdx") || e.endsWith(".md"))) {
+            return true;
+        }
+    }
+    // Check for astro.config with starlight
+    for (const configName of ["astro.config.ts", "astro.config.mjs", "astro.config.js"]) {
+        const configPath = join(path, configName);
+        if (existsSync(configPath)) {
+            const content = readFileSync(configPath, "utf-8");
+            if (content.includes("@astrojs/starlight"))
+                return true;
+        }
+    }
+    // Check if the path itself is a docs directory with .mdx files
+    if (existsSync(path)) {
+        try {
+            const entries = readdirSync(path);
+            const hasMdx = entries.some((e) => e.endsWith(".mdx") || e.endsWith(".md"));
+            // Check a sample file for Starlight frontmatter
+            if (hasMdx) {
+                const sample = entries.find((e) => e.endsWith(".mdx") || e.endsWith(".md"));
+                if (sample) {
+                    const content = readFileSync(join(path, sample), "utf-8");
+                    if (content.includes("sidebar:") && content.includes("order:"))
+                        return true;
+                }
+            }
+        }
+        catch {
+            // Not a directory or can't read
+        }
+    }
+    return false;
+}
+/**
+ * Walk a directory tree and collect all .mdx/.md files.
+ */
+function walkMdxFiles(dir, rootDir) {
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkMdxFiles(fullPath, rootDir));
+        }
+        else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+            const rel = relative(rootDir, fullPath)
+                .replace(/\\/g, "/")
+                .replace(/\.mdx?$/, "")
+                .replace(/\/index$/, "");
+            results.push({ filePath: fullPath, slug: rel || "index" });
+        }
+    }
+    return results;
+}
+/**
+ * Import a Starlight docs source directory.
+ */
+async function importStarlight(source, opts) {
+    // Determine the docs directory
+    let docsDir = source;
+    const srcContentDocs = join(source, "src", "content", "docs");
+    if (existsSync(srcContentDocs)) {
+        docsDir = srcContentDocs;
+    }
+    // Determine href prefix. Defaults to "/docs" but the CLI threads
+    // `site.basePath` (normalized) through opts.hrefPrefix so a site
+    // configured for a different prefix (or root-served, "") gets nav
+    // hrefs matching where pages will actually be emitted.
+    const hrefPrefix = typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : "/docs";
+    // Build nav
+    let nav = null;
+    // Try Mode 1: explicit config
+    for (const configName of ["astro.config.ts", "astro.config.mjs", "astro.config.js"]) {
+        const configPath = join(source, configName);
+        if (existsSync(configPath)) {
+            nav = buildNavFromConfig(configPath, docsDir, hrefPrefix);
+            if (nav)
+                break;
+        }
+    }
+    // Fall back to Mode 2: directory scan
+    if (!nav) {
+        nav = buildNavFromDirectory(docsDir, hrefPrefix);
+    }
+    // Resolve adapter
+    const adapterName = opts.adapter;
+    const adapter = adapterName ? ADAPTERS[adapterName] : undefined;
+    if (adapterName && !adapter) {
+        console.warn(`Warning: Unknown adapter "${adapterName}". Available: ${Object.keys(ADAPTERS).join(", ")}`);
+    }
+    // Auto-detect partials directory
+    // Walk up from docsDir to find src/content/partials/
+    let partialsDir;
+    let searchDir = docsDir;
+    for (let depth = 0; depth < 10; depth++) {
+        const candidate = join(searchDir, "src", "content", "partials");
+        if (existsSync(candidate)) {
+            partialsDir = candidate;
+            break;
+        }
+        // Also check if partials is a sibling of our current path
+        const sibling = join(dirname(searchDir), "partials");
+        if (existsSync(sibling)) {
+            partialsDir = sibling;
+            break;
+        }
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    // Allow explicit override via CLI option
+    if (opts.partialsDir) {
+        partialsDir = opts.partialsDir;
+    }
+    // Parse all pages
+    const mdxFiles = walkMdxFiles(docsDir, docsDir);
+    const pages = [];
+    // Custom taxonomy names from dogsbay.config.yml's `taxonomies:` block
+    // (threaded through cli's import-content.ts).
+    const taxonomyNames = Array.isArray(opts.taxonomyNames)
+        ? opts.taxonomyNames
+        : undefined;
+    for (const { filePath, slug } of mdxFiles) {
+        const content = readFileSync(filePath, "utf-8");
+        const { frontmatter, raw, body } = extractFrontmatter(content);
+        // Use new MDX parser (markdown-it-mdx-jsx plugin) by default
+        // Fall back to legacy regex parser with --legacy-parser flag
+        const useLegacy = opts.legacyParser === true;
+        const starlightToTree = useLegacy ? starlightToTreeLegacy : starlightToTreeMdx;
+        const tree = starlightToTree(body, { adapter, partialsDir });
+        // Extract headings from tree
+        const headings = tree
+            .filter((n) => n.type === "heading")
+            .map((n) => ({
+            depth: n.props?.level,
+            text: n.props?.text,
+            slug: n.props?.slug,
+        }));
+        // Check for redirect pages (adapter-configurable frontmatter field)
+        let redirect;
+        if (adapter?.redirectField) {
+            const redirectMatch = content.match(new RegExp(`^${adapter.redirectField}:\\s*(.+)$`, "m"));
+            if (redirectMatch) {
+                redirect = redirectMatch[1].trim().replace(/^["']|["']$/g, "");
+            }
+        }
+        // Generate visible content for redirect pages with empty body
+        if (redirect && tree.length === 0) {
+            tree.push({
+                type: "callout",
+                props: { variant: "info" },
+                children: [
+                    {
+                        type: "paragraph",
+                        children: [
+                            {
+                                type: "prose",
+                                inline: [
+                                    { type: "text", text: "This page redirects to ", bold: false, italic: false },
+                                    {
+                                        type: "link",
+                                        href: redirect,
+                                        children: [
+                                            { type: "text", text: frontmatter.title || slug, bold: false, italic: false },
+                                        ],
+                                    },
+                                    { type: "text", text: ".", bold: false, italic: false },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            });
+        }
+        const title = frontmatter.title || slug;
+        const meta = parseMeta(raw, { slug, taxonomyNames });
+        pages.push({
+            slug,
+            title,
+            tree,
+            headings,
+            redirect,
+            frontmatter: raw,
+            meta,
+        });
+    }
+    // Set site name from opts or infer
+    if (!opts.siteName && pages.length > 0) {
+        const indexPage = pages.find((p) => p.slug === "index" || p.slug === "");
+        if (indexPage) {
+            opts.siteName = indexPage.title;
+        }
+    }
+    return { pages, nav };
+}
+export const plugin = {
+    name: "starlight",
+    canImport: true,
+    canExport: false,
+    detectSource: detectStarlightSource,
+    exportOptions: [
+        { flags: "--adapter <name>", description: "Site adapter for custom components (e.g. cloudflare)" },
+    ],
+    async import(source, opts) {
+        return importStarlight(source, opts);
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { starlightToTree as starlightToTreeLegacy, extractFrontmatter } from "./parse.js";
+export { starlightToTree } from "./parse-mdx.js";
+export type { ParseOptions } from "./parse-mdx.js";
+export { buildNavFromDirectory, buildNavFromConfig } from "./nav.js";
+export type { ComponentMapping, SiteAdapter } from "./adapter.js";
+export { cloudflareAdapter } from "./adapters/cloudflare.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { starlightToTree as starlightToTreeLegacy, extractFrontmatter } from "./parse.js";
+export { starlightToTree } from "./parse-mdx.js";
+export { buildNavFromDirectory, buildNavFromConfig } from "./nav.js";
+export { cloudflareAdapter } from "./adapters/cloudflare.js";

package/dist/nav.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Nav builder for Starlight sites.
+ *
+ * Two modes:
+ *   1. buildNavFromDirectory — Scan filesystem + frontmatter sidebar.order/label (Mode 2)
+ *   2. buildNavFromConfig — Parse explicit sidebar config from astro.config.ts (Mode 1)
+ *
+ * Both produce the same NavItem[] output.
+ */
+import type { NavItem } from "@dogsbay/types";
+/**
+ * Build nav from directory structure and frontmatter sidebar.order.
+ *
+ * Scans the docs directory, reads frontmatter from each .mdx/.md file,
+ * and builds a hierarchical nav sorted by sidebar.order.
+ *
+ * @param docsDir - The directory containing .mdx source files (e.g. src/content/docs/ddos-protection/)
+ * @param hrefPrefix - Prefix for href values (e.g. "/docs/ddos-protection")
+ */
+export declare function buildNavFromDirectory(docsDir: string, hrefPrefix?: string): NavItem[];
+/**
+ * Attempt to extract sidebar config from astro.config.ts.
+ *
+ * This is a best-effort parser — it handles static sidebar arrays
+ * but cannot resolve dynamic expressions (e.g. Cloudflare's autogenSections()).
+ * Returns null if the sidebar can't be parsed statically.
+ *
+ * @param configPath - Path to astro.config.ts or astro.config.mjs
+ * @param docsDir - Docs directory for resolving autogenerate directives
+ * @param hrefPrefix - Prefix for href values
+ */
+export declare function buildNavFromConfig(configPath: string, docsDir: string, hrefPrefix?: string): NavItem[] | null;

package/dist/nav.js

@@ -0,0 +1,332 @@
+/**
+ * Nav builder for Starlight sites.
+ *
+ * Two modes:
+ *   1. buildNavFromDirectory — Scan filesystem + frontmatter sidebar.order/label (Mode 2)
+ *   2. buildNavFromConfig — Parse explicit sidebar config from astro.config.ts (Mode 1)
+ *
+ * Both produce the same NavItem[] output.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { extractFrontmatter } from "./parse.js";
+/**
+ * Build nav from directory structure and frontmatter sidebar.order.
+ *
+ * Scans the docs directory, reads frontmatter from each .mdx/.md file,
+ * and builds a hierarchical nav sorted by sidebar.order.
+ *
+ * @param docsDir - The directory containing .mdx source files (e.g. src/content/docs/ddos-protection/)
+ * @param hrefPrefix - Prefix for href values (e.g. "/docs/ddos-protection")
+ */
+export function buildNavFromDirectory(docsDir, hrefPrefix = "/docs") {
+    const pages = collectPages(docsDir, docsDir);
+    return buildHierarchy(pages, hrefPrefix);
+}
+function collectPages(dir, rootDir) {
+    const pages = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            pages.push(...collectPages(fullPath, rootDir));
+        }
+        else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+            const content = readFileSync(fullPath, "utf-8");
+            const { frontmatter } = extractFrontmatter(content);
+            if (frontmatter.sidebarHidden)
+                continue;
+            // Build slug from file path relative to root dir
+            let slug = relative(rootDir, fullPath)
+                .replace(/\\/g, "/")
+                .replace(/\.mdx?$/, "")
+                .replace(/\/index$/, "");
+            pages.push({
+                title: frontmatter.title,
+                sidebarLabel: frontmatter.sidebarLabel,
+                sidebarOrder: frontmatter.sidebarOrder,
+                sidebarHidden: frontmatter.sidebarHidden,
+                hideIndex: frontmatter.hideIndex,
+                slug,
+                filePath: fullPath,
+            });
+        }
+    }
+    return pages;
+}
+function buildHierarchy(pages, hrefPrefix) {
+    // Determine which slugs are directory index pages (i.e. there are other pages under that path)
+    const allSlugs = new Set(pages.map((p) => p.slug));
+    const directorySlugs = new Set();
+    for (const page of pages) {
+        const parts = page.slug.split("/");
+        if (parts.length > 1) {
+            // Mark all ancestor directories
+            for (let i = 1; i < parts.length; i++) {
+                directorySlugs.add(parts.slice(0, i).join("/"));
+            }
+        }
+    }
+    // Group pages by their top-level directory
+    const groups = new Map();
+    const topLevel = [];
+    for (const page of pages) {
+        const parts = page.slug.split("/");
+        if (parts.length > 1) {
+            // Has parent directory — group under top-level dir
+            const group = parts[0];
+            if (!groups.has(group))
+                groups.set(group, []);
+            groups.get(group).push(page);
+        }
+        else if (directorySlugs.has(page.slug)) {
+            // This is an index page for a directory — it becomes the group header, not a top-level item
+            const group = page.slug;
+            if (!groups.has(group))
+                groups.set(group, []);
+            groups.get(group).push(page);
+        }
+        else {
+            // True top-level leaf page
+            topLevel.push(page);
+        }
+    }
+    const entries = [];
+    // Top-level leaf pages
+    for (const page of topLevel) {
+        entries.push({
+            order: page.sidebarOrder ?? 999,
+            item: pageToNavItem(page, hrefPrefix),
+        });
+    }
+    // Groups
+    for (const [groupName, groupPages] of groups) {
+        const indexPage = groupPages.find((p) => p.slug === groupName);
+        // Group label uses title, not sidebarLabel.
+        const label = indexPage?.title || slugToLabel(groupName);
+        const children = buildGroupChildren(groupPages, groupName, hrefPrefix);
+        if (children.length > 0) {
+            const href = indexPage ? `${hrefPrefix}/${indexPage.slug}` : undefined;
+            entries.push({
+                order: indexPage?.sidebarOrder ?? 999,
+                item: { label, href, children },
+            });
+        }
+    }
+    // Sort by order, then alphabetically
+    entries.sort((a, b) => {
+        if (a.order !== b.order)
+            return a.order - b.order;
+        return (a.item.label || "").localeCompare(b.item.label || "");
+    });
+    const nav = entries.map((e) => e.item);
+    return nav;
+}
+function buildGroupChildren(pages, groupName, hrefPrefix) {
+    // Separate into sub-groups and leaf pages
+    const subGroups = new Map();
+    const leaves = [];
+    // Find the index page for this group
+    const indexPage = pages.find((p) => p.slug === groupName);
+    // First pass: collect sub-group directories
+    for (const page of pages) {
+        if (page.slug === groupName)
+            continue;
+        const rel = page.slug.startsWith(groupName + "/")
+            ? page.slug.slice(groupName.length + 1)
+            : page.slug;
+        const parts = rel.split("/");
+        if (parts.length > 1) {
+            const subGroup = parts[0];
+            const key = `${groupName}/${subGroup}`;
+            if (!subGroups.has(key))
+                subGroups.set(key, []);
+            subGroups.get(key).push(page);
+        }
+    }
+    // Second pass: collect leaf pages, but skip those that are index pages of sub-groups
+    for (const page of pages) {
+        if (page.slug === groupName)
+            continue;
+        const rel = page.slug.startsWith(groupName + "/")
+            ? page.slug.slice(groupName.length + 1)
+            : page.slug;
+        const parts = rel.split("/");
+        if (parts.length === 1) {
+            // Check if this leaf's slug matches a sub-group directory
+            const potentialSubGroup = `${groupName}/${rel}`;
+            if (subGroups.has(potentialSubGroup)) {
+                // This is the index page for a sub-group — add it to that sub-group's pages
+                subGroups.get(potentialSubGroup).push(page);
+            }
+            else {
+                leaves.push(page);
+            }
+        }
+    }
+    const children = [];
+    // Add index page as first child of the group — unless hideIndex is set.
+    // Starlight's sidebar.group.hideIndex suppresses the index page from children.
+    // When shown: "Overview" if title matches group label, else the page's own title.
+    if (indexPage && !indexPage.hideIndex) {
+        const indexTitle = indexPage.sidebarLabel || indexPage.title || "";
+        const normalize = (s) => s.toLowerCase().replace(/[\s-]+/g, "");
+        const groupSlug = groupName.split("/").pop() || groupName;
+        const isGenericIndex = normalize(indexTitle) === normalize(groupSlug) ||
+            normalize(indexTitle) === normalize(slugToLabel(groupSlug));
+        children.push({
+            label: isGenericIndex ? "Overview" : indexTitle,
+            href: `${hrefPrefix}/${indexPage.slug}`,
+        });
+    }
+    const entries = [];
+    // Leaves
+    for (const page of leaves) {
+        entries.push({
+            order: page.sidebarOrder ?? 999,
+            item: pageToNavItem(page, hrefPrefix),
+        });
+    }
+    // Sub-groups
+    for (const [subGroupPath, subPages] of subGroups) {
+        const subGroupSlug = subGroupPath.split("/").pop();
+        const subIndex = subPages.find((p) => p.slug === subGroupPath);
+        const label = subIndex?.title || slugToLabel(subGroupSlug);
+        const order = subIndex?.sidebarOrder ?? 999;
+        const subChildren = buildGroupChildren(subPages, subGroupPath, hrefPrefix);
+        if (subChildren.length > 0) {
+            const href = subIndex ? `${hrefPrefix}/${subIndex.slug}` : undefined;
+            entries.push({ order, item: { label, href, children: subChildren } });
+        }
+    }
+    // Sort by order, then alphabetically
+    entries.sort((a, b) => {
+        if (a.order !== b.order)
+            return a.order - b.order;
+        return (a.item.label || "").localeCompare(b.item.label || "");
+    });
+    for (const entry of entries) {
+        children.push(entry.item);
+    }
+    return children;
+}
+function pageToNavItem(page, hrefPrefix) {
+    const label = page.sidebarLabel || page.title || slugToLabel(page.slug);
+    const href = `${hrefPrefix}/${page.slug}`;
+    return { label, href };
+}
+function sortPages(pages) {
+    pages.sort((a, b) => {
+        const orderA = a.sidebarOrder ?? 999;
+        const orderB = b.sidebarOrder ?? 999;
+        if (orderA !== orderB)
+            return orderA - orderB;
+        return a.title.localeCompare(b.title);
+    });
+}
+function slugToLabel(slug) {
+    const name = slug.split("/").pop() || slug;
+    return name
+        .split("-")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+// ── Mode 1: Build nav from astro.config sidebar ─────────
+/**
+ * Attempt to extract sidebar config from astro.config.ts.
+ *
+ * This is a best-effort parser — it handles static sidebar arrays
+ * but cannot resolve dynamic expressions (e.g. Cloudflare's autogenSections()).
+ * Returns null if the sidebar can't be parsed statically.
+ *
+ * @param configPath - Path to astro.config.ts or astro.config.mjs
+ * @param docsDir - Docs directory for resolving autogenerate directives
+ * @param hrefPrefix - Prefix for href values
+ */
+export function buildNavFromConfig(configPath, docsDir, hrefPrefix = "/docs") {
+    let content;
+    try {
+        content = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    // Find the sidebar array — look for sidebar: [ ... ]
+    const sidebarMatch = content.match(/sidebar:\s*\[/);
+    if (!sidebarMatch)
+        return null;
+    // Extract the array by tracking bracket depth
+    const start = sidebarMatch.index + sidebarMatch[0].length - 1;
+    let depth = 0;
+    let end = start;
+    for (let i = start; i < content.length; i++) {
+        if (content[i] === "[")
+            depth++;
+        else if (content[i] === "]") {
+            depth--;
+            if (depth === 0) {
+                end = i + 1;
+                break;
+            }
+        }
+    }
+    const sidebarStr = content.slice(start, end);
+    // Try to parse as JSON5-like (remove trailing commas, handle unquoted keys)
+    let sidebarData;
+    try {
+        const jsonLike = sidebarStr
+            .replace(/(\w+):/g, '"$1":') // quote keys
+            .replace(/'/g, '"') // single to double quotes
+            .replace(/,\s*([}\]])/g, "$1") // trailing commas
+            .replace(/\/\/.*/g, ""); // strip comments
+        sidebarData = JSON.parse(jsonLike);
+    }
+    catch {
+        // Config is too dynamic to parse statically
+        return null;
+    }
+    return sidebarDataToNav(sidebarData, docsDir, hrefPrefix);
+}
+function sidebarDataToNav(items, docsDir, hrefPrefix) {
+    const nav = [];
+    for (const item of items) {
+        if (typeof item === "string") {
+            // Slug shorthand
+            nav.push({ label: slugToLabel(item), href: `${hrefPrefix}/${item}` });
+        }
+        else if (typeof item === "object" && item !== null) {
+            const obj = item;
+            if (obj.slug) {
+                // Explicit slug reference
+                const slug = obj.slug;
+                const label = obj.label || slugToLabel(slug);
+                nav.push({ label, href: `${hrefPrefix}/${slug}` });
+            }
+            else if (obj.link) {
+                // URL link
+                const label = obj.label || "";
+                nav.push({ label, href: obj.link });
+            }
+            else if (obj.items) {
+                // Group with nested items
+                const label = obj.label || "";
+                const children = sidebarDataToNav(obj.items, docsDir, hrefPrefix);
+                nav.push({ label, children });
+            }
+            else if (obj.autogenerate) {
+                // Autogenerate from directory
+                const label = obj.label || "";
+                const dir = obj.autogenerate.directory;
+                const fullDir = join(docsDir, dir);
+                try {
+                    const children = buildNavFromDirectory(fullDir, `${hrefPrefix}/${dir}`);
+                    nav.push({ label, children });
+                }
+                catch {
+                    // Directory doesn't exist or can't be read
+                    nav.push({ label, children: [] });
+                }
+            }
+        }
+    }
+    return nav;
+}

package/dist/parse-mdx.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Starlight MDX parser — v2 using markdown-it-mdx-jsx plugin.
+ *
+ * Replaces the regex-based segmentMdx approach with proper JSX token handling.
+ * The markdown-it-mdx-jsx plugin emits jsx_open/jsx_close/jsx_self_closing
+ * tokens that are handled alongside standard markdown tokens.
+ *
+ * Keeps:
+ * - Directive conversion (:::note → <Aside>)
+ * - Inline transforms (adapter.inlineTransforms)
+ * - Steps unwrapping (steps > ordered-list > list-item → steps > step)
+ * - Card grouping (consecutive cards → cards container)
+ * - The adapter pattern for site-specific component mappings
+ */
+import type { TreeNode } from "@dogsbay/types";
+import type { SiteAdapter } from "./adapter.js";
+export interface ParseOptions {
+    adapter?: SiteAdapter;
+    /** Directory containing partial MDX files for <Render> resolution */
+    partialsDir?: string;
+}
+export declare function starlightToTree(source: string, options?: ParseOptions): TreeNode[];