@dogsbay/format-docusaurus 0.2.0-beta.78

package/dist/sidebars.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parse a Docusaurus sidebars module into NavItem[] (Mode 1 — explicit sidebar).
+ *
+ * A sidebars file exports one or more named sidebars:
+ *   module.exports = { calicoSidebar: [ ...items ] }
+ *
+ * Item shapes (https://docusaurus.io/docs/sidebar/items):
+ *   - 'doc/id'                                         shorthand doc link
+ *   - { type: 'doc', id, label? }                      doc link
+ *   - { type: 'ref', id, label? }                      doc link (no sidebar membership)
+ *   - { type: 'link', href, label }                    explicit/external link
+ *   - { type: 'category', label, link?, items, ... }   group
+ *   - { type: 'autogenerated', dirName }               expand from the filesystem
+ *   - { type: 'html' }                                 decorative — skipped
+ *
+ * Doc-id → href and doc-id → label resolution, plus autogenerated expansion,
+ * are injected via SidebarContext so this module stays free of filesystem I/O
+ * and is unit-testable.
+ */
+import type { NavItem } from "@dogsbay/types";
+export interface RawCategoryLink {
+    type: "doc" | "generated-index" | string;
+    id?: string;
+    title?: string;
+    permalink?: string;
+}
+export type RawSidebarItem = string | {
+    type: "doc";
+    id: string;
+    label?: string;
+} | {
+    type: "ref";
+    id: string;
+    label?: string;
+} | {
+    type: "link";
+    href: string;
+    label: string;
+} | {
+    type: "category";
+    label: string;
+    link?: RawCategoryLink | null;
+    items: RawSidebarItem[];
+    collapsed?: boolean;
+} | {
+    type: "autogenerated";
+    dirName: string;
+} | {
+    type: "html";
+    value?: string;
+} | Record<string, unknown>;
+export type RawSidebars = Record<string, RawSidebarItem[]>;
+export interface SidebarContext {
+    /** doc id → href (e.g. "about/index" → "/docs/about"). */
+    docHref: (id: string) => string;
+    /** doc id → display label (frontmatter sidebar_label/title, else derived). */
+    docLabel: (id: string) => string;
+    /** Expand an autogenerated category over a directory → NavItem[]. */
+    expandAutogenerated?: (dirName: string) => NavItem[];
+}
+/** Load a sidebars module via the CJS loader (single trust boundary). */
+export declare function loadSidebars(sidebarPath: string): Promise<RawSidebars>;
+/**
+ * Build NavItem[] from a loaded sidebars module. All named sidebars in the
+ * module are concatenated (a docs instance usually defines exactly one).
+ */
+export declare function buildNavFromSidebars(sidebars: RawSidebars, ctx: SidebarContext): NavItem[];

package/dist/sidebars.js

@@ -0,0 +1,65 @@
+import { loadCjs } from "./load-cjs.js";
+/** Load a sidebars module via the CJS loader (single trust boundary). */
+export async function loadSidebars(sidebarPath) {
+    const mod = await loadCjs(sidebarPath);
+    return mod ?? {};
+}
+function itemToNav(item, ctx) {
+    // Shorthand string → doc link.
+    if (typeof item === "string") {
+        return { label: ctx.docLabel(item), href: ctx.docHref(item) };
+    }
+    const type = item.type;
+    if (type === "doc" || type === "ref") {
+        const it = item;
+        return { label: it.label ?? ctx.docLabel(it.id), href: ctx.docHref(it.id) };
+    }
+    if (type === "link") {
+        const it = item;
+        return { label: it.label, href: it.href };
+    }
+    if (type === "autogenerated") {
+        const it = item;
+        return ctx.expandAutogenerated ? ctx.expandAutogenerated(it.dirName) : [];
+    }
+    if (type === "html") {
+        return null;
+    }
+    if (type === "category") {
+        const it = item;
+        const children = buildItems(it.items ?? [], ctx);
+        const nav = { label: it.label, children };
+        // A category linking to a doc becomes clickable and gets that doc as its href.
+        if (it.link && it.link.type === "doc" && it.link.id) {
+            nav.href = ctx.docHref(it.link.id);
+        }
+        return nav;
+    }
+    return null;
+}
+function buildItems(items, ctx) {
+    const out = [];
+    for (const item of items) {
+        const nav = itemToNav(item, ctx);
+        if (!nav)
+            continue;
+        if (Array.isArray(nav))
+            out.push(...nav);
+        else
+            out.push(nav);
+    }
+    return out;
+}
+/**
+ * Build NavItem[] from a loaded sidebars module. All named sidebars in the
+ * module are concatenated (a docs instance usually defines exactly one).
+ */
+export function buildNavFromSidebars(sidebars, ctx) {
+    const out = [];
+    for (const key of Object.keys(sidebars)) {
+        const items = sidebars[key];
+        if (Array.isArray(items))
+            out.push(...buildItems(items, ctx));
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dogsbay/format-docusaurus",
+  "version": "0.2.0-beta.78",
+  "description": "Generic Docusaurus importer for Dogsbay — converts standard Docusaurus docs (config instances, sidebars, MDX with Tabs/admonitions/CodeBlock) into TreeNode[]. Site-specific extensions live in injected adapter packages.",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^14.1.0",
+    "@dogsbay/markdown-it-mdx-jsx": "0.2.0-beta.78",
+    "@dogsbay/types": "0.2.0-beta.78"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/format-docusaurus"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}