@dogsbay/adapter-posthog 0.0.0-stage → 0.2.0-beta.136

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PostHog site adapter for @dogsbay/format-gatsby.
+ *
+ * Two jobs (the generic importer owns the rest): map PostHog's
+ * globally-injected MDX components to Dogsbay directives (or strip +
+ * ledger the interactive long tail), and extract the nav from
+ * `src/navs/index.js`.
+ */
+import type { GatsbyAdapter } from "@dogsbay/format-gatsby";
+export declare const posthogAdapter: GatsbyAdapter;
+export default posthogAdapter;

package/dist/index.js

@@ -0,0 +1,241 @@
+/**
+ * PostHog site adapter for @dogsbay/format-gatsby.
+ *
+ * Two jobs (the generic importer owns the rest): map PostHog's
+ * globally-injected MDX components to Dogsbay directives (or strip +
+ * ledger the interactive long tail), and extract the nav from
+ * `src/navs/index.js`.
+ */
+import { extractPosthogNav } from "./nav.js";
+/** PostHog CalloutBox `type` → Dogsbay callout kind. */
+const CALLOUT_TYPE = {
+    fyi: "note",
+    info: "info",
+    action: "tip",
+    tip: "tip",
+    caution: "caution",
+    warning: "warning",
+    danger: "danger",
+    task: "note",
+};
+/** A remote-image component (`imageLight`/`image`/`src` → an image node). */
+function imageMapping() {
+    return {
+        type: "image",
+        container: false,
+        propsFromAttrs: (a) => ({
+            src: a.imageLight ?? a.imageDark ?? a.image ?? a.src ?? "",
+            alt: a.alt ?? "",
+        }),
+    };
+}
+/** Drop a component entirely (wrapper + inner), recorded in the ledger. */
+const dropAll = {
+    type: "callout",
+    container: true,
+    strip: true,
+    children: "ignore",
+};
+/** Unwrap a component: drop the wrapper, keep its inner blocks. */
+const unwrap = {
+    type: "callout",
+    container: true,
+    strip: true,
+    children: "blocks",
+};
+/** Emit a fixed code block (for near-static data-driven components). */
+function codeNode(code, language = "bash") {
+    return { type: "code", container: false, toNode: () => ({ type: "code", props: { code, language } }) };
+}
+/**
+ * Placeholder for a data-driven React component that has NO static
+ * markdown source (logo grids, generated snippets). Honest + ledgered:
+ * the panel shows what's missing rather than rendering blank.
+ */
+function placeholder(label) {
+    return {
+        type: "callout",
+        container: false,
+        toNode: () => ({
+            type: "callout",
+            props: { type: "info" },
+            children: [
+                {
+                    // `type: "html"` so the markup survives both the direct
+                    // tree→astro serializer and the dogsbay-md round-trip; a
+                    // paragraph's `.html` is only honored on the latter.
+                    type: "html",
+                    html: `<p><strong>${label}</strong> is generated by an interactive component on posthog.com and has no static source in the docs — see the <a href="https://posthog.com/docs">live docs</a>.</p>`,
+                },
+            ],
+        }),
+    };
+}
+const components = {
+    // --- clean directive maps (the 80% win) ---
+    ProductScreenshot: imageMapping(),
+    ProductVideo: imageMapping(),
+    CalloutBox: {
+        type: "callout",
+        container: true,
+        children: "blocks",
+        propsFromAttrs: (a) => ({ type: CALLOUT_TYPE[(a.type ?? "").toLowerCase()] ?? "note" }),
+    },
+    Caption: { type: "paragraph", container: true, children: "blocks" },
+    // MultiLanguage wraps language-labelled fences; unwrap to keep the code.
+    MultiLanguage: unwrap,
+    // --- interactive / data-driven long tail: drop, ledgered ---
+    QuestLog: dropAll,
+    QuestLogItem: dropAll,
+    OSButton: dropAll,
+    PostHogProvider: unwrap,
+    PostHogFeature: unwrap,
+    PostHogPageView: dropAll,
+    OnboardingContentWrapper: unwrap,
+    CallToAction: dropAll,
+    PromptExample: unwrap,
+    SolvedQuestions: dropAll,
+    AskAIInput: dropAll,
+    ProductChangelog: dropAll,
+    SettingProperties: dropAll,
+    DetailPostHogIPs: dropAll,
+    SourceParameters: dropAll,
+    FeatureAvailability: dropAll,
+    // --- additional data-driven long tail (surfaced by the full run) ---
+    SourceTables: dropAll,
+    SourceSetupIntro: dropAll,
+    SyncModes: dropAll,
+    TemplateParameters: dropAll,
+    TroubleshootingLink: dropAll,
+    AlphaRelease: dropAll,
+    BetaTag: dropAll,
+    ProductCard: dropAll,
+    PostHogIPsInline: dropAll,
+    PostHogIPsTable: dropAll,
+    PostHogCaptureOnViewed: unwrap,
+    MCPConfigSnippet: dropAll,
+    ComparisonRow: dropAll,
+    DistinctIdReuseWarning: dropAll,
+    DetailSetUpReverseProxy: dropAll,
+    DetailGroupProductsInOneProject: dropAll,
+    // conditional/layout wrappers → unwrap (keep the inner prose)
+    HideOnCDPIndex: unwrap,
+    Link: unwrap,
+    // --- data-driven React with no static markdown: recover what's static,
+    //     placeholder the rest (honest, ledgered) instead of a blank panel ---
+    WizardCommand: codeNode("npx @posthog/wizard"),
+    WizardSupportedFrameworks: placeholder("Supported frameworks & languages"),
+    SDKs: placeholder("PostHog SDKs / client libraries"),
+    Frameworks: placeholder("Framework guides"),
+    WebsiteJSHtmlSnippet: placeholder("JavaScript web install snippet"),
+    Wizard: unwrap,
+    API: placeholder("API reference overview"),
+};
+/** Human labels for common `<MultiLanguage>` fence languages. */
+const LANG_LABEL = {
+    "js-web": "Web",
+    js: "JavaScript",
+    ts: "TypeScript",
+    node: "Node.js",
+    "react-native": "React Native",
+    ios_swift: "iOS",
+    swift: "iOS",
+    android_kotlin: "Android",
+    kotlin: "Android",
+    python: "Python",
+    ruby: "Ruby",
+    php: "PHP",
+    go: "Go",
+    csharp: "C#",
+    java: "Java",
+    bash: "Shell",
+    curl: "cURL",
+};
+function prettify(s) {
+    return LANG_LABEL[s] ?? s.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+const escAttr = (s) => s.replace(/"/g, "&quot;");
+/**
+ * Convert PostHog's tab-like components to the `<Tabs><Tab label=…>`
+ * shape format-mdx's builtins turn into real Dogsbay `:::tabs` — so the
+ * tab UX is preserved instead of flattened. Two forms:
+ *
+ *  - `<Tab.Group>` (Headless-UI, dotted namespace): labels from the
+ *    `<Tab.List>` `<Tab>…</Tab>` items, one panel per `<Tab.Panel>`.
+ *  - `<MultiLanguage>`: one tab per fenced code block, labelled by the
+ *    fence language.
+ *
+ * These are always prose (never inside code fences), so a raw-text
+ * rewrite before parsing is safe.
+ */
+function convertTabs(src) {
+    // 1. Tab.Group → Tabs
+    src = src.replace(/<Tab\.Group\b[^>]*>([\s\S]*?)<\/Tab\.Group>/g, (_full, body) => {
+        const listM = body.match(/<Tab\.List>([\s\S]*?)<\/Tab\.List>/);
+        const labels = listM
+            ? [...listM[1].matchAll(/<Tab\b[^>]*>([\s\S]*?)<\/Tab>/g)].map((m) => m[1].replace(/<[^>]+>/g, "").trim())
+            : [];
+        const panels = [
+            ...body.matchAll(/<Tab\.Panel\b[^>]*>([\s\S]*?)<\/Tab\.Panel>/g),
+        ].map((m) => m[1].trim());
+        if (panels.length === 0)
+            return body.replace(/<\/?Tab\.[A-Za-z]+\b[^>]*>/g, "");
+        const tabs = panels
+            .map((p, i) => `<Tab label="${escAttr(labels[i] ?? `Tab ${i + 1}`)}">\n\n${p}\n\n</Tab>`)
+            .join("\n");
+        return `<Tabs>\n${tabs}\n</Tabs>`;
+    });
+    // 2. MultiLanguage → Tabs (one tab per fenced block, labelled by lang)
+    src = src.replace(/<MultiLanguage\b[^>]*>([\s\S]*?)<\/MultiLanguage>/g, (_full, body) => {
+        const fences = [...body.matchAll(/```([\w-]*)\r?\n([\s\S]*?)```/g)];
+        if (fences.length < 2)
+            return body; // 0-1 fences: no tabs needed, keep content
+        const tabs = fences
+            .map(([, lang, code]) => `<Tab label="${escAttr(prettify(lang || "Example"))}">\n\n\`\`\`${lang}\n${code}\`\`\`\n\n</Tab>`)
+            .join("\n");
+        return `<Tabs>\n${tabs}\n</Tabs>`;
+    });
+    return src;
+}
+const mdx = {
+    name: "posthog",
+    preprocess: (source) => convertTabs(source),
+    components,
+    selfClosingTags: [
+        "ProductScreenshot",
+        "ProductVideo",
+        "SourceTables",
+        "SourceSetupIntro",
+        "SyncModes",
+        "TemplateParameters",
+        "TroubleshootingLink",
+        "AlphaRelease",
+        "BetaTag",
+        "ProductCard",
+        "PostHogIPsInline",
+        "PostHogIPsTable",
+        "MCPConfigSnippet",
+        "DistinctIdReuseWarning",
+        "WizardSupportedFrameworks",
+        "DetailSetUpReverseProxy",
+        "DetailGroupProductsInOneProject",
+        "DetailPostHogIPs",
+        "FeatureAvailability",
+        "WizardCommand",
+        "WizardSupportedFrameworks",
+        "SDKs",
+        "Frameworks",
+        "WebsiteJSHtmlSnippet",
+        "API",
+    ],
+    // Strip inline icon components (`<IconGraph />`) that ride inside prose.
+    inlineTransforms: [[/<Icon[A-Za-z0-9]+\b[^>]*\/>/g, ""]],
+};
+export const posthogAdapter = {
+    name: "posthog",
+    mdx,
+    linkBase: "/docs",
+    externalBase: "https://posthog.com",
+    extractNav: ({ sourceDir, hrefPrefix }) => extractPosthogNav(sourceDir, hrefPrefix),
+};
+export default posthogAdapter;

package/dist/nav.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract Dogsbay nav from PostHog's `src/navs/index.js` — a 7.7k-line
+ * hand-maintained module of `export const <product> = { name, url,
+ * children: [...] }` trees. It is PURE static data (string icons, no JS
+ * imports), so it is statically readable without execution: this walker
+ * captures each exported object literal and maps it to NavItem[] using
+ * the same balanced-literal scanners format-mdx uses for TSX sidebars.
+ *
+ * `dynamicChildren` (API-injected, only 4 in the tree) are ignored here
+ * — the static children present alongside them are kept; the injected
+ * ones are a known, ledgered gap.
+ */
+import type { NavItem } from "@dogsbay/format-mdx";
+/** Locate PostHog's navs/index.js relative to the docs source dir. */
+export declare function findNavModule(sourceDir: string): string | null;
+/**
+ * PostHog's canonical docs nav is the single `export const docsMenu`
+ * object (its children are the product groups). The other object exports
+ * (`communityMenu`, `companyMenu`, `pricingMenu`, …) are the marketing
+ * nav — deliberately excluded.
+ */
+export declare function extractPosthogNav(sourceDir: string, hrefPrefix: string): NavItem[] | null;

package/dist/nav.js

@@ -0,0 +1,123 @@
+/**
+ * Extract Dogsbay nav from PostHog's `src/navs/index.js` — a 7.7k-line
+ * hand-maintained module of `export const <product> = { name, url,
+ * children: [...] }` trees. It is PURE static data (string icons, no JS
+ * imports), so it is statically readable without execution: this walker
+ * captures each exported object literal and maps it to NavItem[] using
+ * the same balanced-literal scanners format-mdx uses for TSX sidebars.
+ *
+ * `dynamicChildren` (API-injected, only 4 in the tree) are ignored here
+ * — the static children present alongside them are kept; the injected
+ * ones are a known, ledgered gap.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsObjectEntries, parseJsArrayElements, scanBalancedLiteral, } from "@dogsbay/format-mdx";
+function unquote(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.trim().match(/^(["'`])([\s\S]*)\1$/);
+    return m ? m[2] : undefined;
+}
+function objToNav(objSrc) {
+    const entries = parseJsObjectEntries(objSrc);
+    if (!entries)
+        return null;
+    const o = Object.fromEntries(entries);
+    const label = unquote(o.name) ?? unquote(o.title) ?? unquote(o.label);
+    if (!label)
+        return null;
+    const nav = { label };
+    const url = unquote(o.url) ?? unquote(o.href);
+    if (url)
+        nav.url = url;
+    const childSrc = o.children?.trim();
+    if (childSrc?.startsWith("[")) {
+        const els = parseJsArrayElements(childSrc);
+        if (els) {
+            const kids = els.map(objToNav).filter((c) => c !== null);
+            if (kids.length)
+                nav.children = kids;
+        }
+    }
+    return nav;
+}
+/** `/docs/cdp/sources` → `cdp/sources` (slug relative to contents/docs). */
+function urlToSlug(url) {
+    return url.replace(/^\/docs\/?/, "").replace(/\/$/, "");
+}
+function toNavItems(raws, hrefPrefix) {
+    const pref = hrefPrefix.replace(/\/$/, "");
+    const out = [];
+    for (const r of raws) {
+        const item = { label: r.label };
+        if (r.url) {
+            if (/^[a-z]+:\/\//.test(r.url))
+                item.href = r.url; // external
+            else {
+                const slug = urlToSlug(r.url);
+                item.href = slug ? `${pref}/${slug}` : pref || "/";
+            }
+        }
+        if (r.children) {
+            const kids = toNavItems(r.children, hrefPrefix);
+            if (kids.length)
+                item.children = kids;
+        }
+        // The Dogsbay nav schema requires href OR children — PostHog's
+        // `{name}`-only section dividers have neither; drop them.
+        if (!item.href && !item.children)
+            continue;
+        out.push(item);
+    }
+    return out;
+}
+const NAV_CANDIDATES = [
+    "../../src/navs/index.js",
+    "../src/navs/index.js",
+    "src/navs/index.js",
+    "../../../src/navs/index.js",
+];
+/** Locate PostHog's navs/index.js relative to the docs source dir. */
+export function findNavModule(sourceDir) {
+    for (const c of NAV_CANDIDATES) {
+        const p = join(sourceDir, c);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Capture the object literal of a named `export const <name> = { … }`. */
+function captureExportObject(src, name) {
+    const re = new RegExp(`export\\s+const\\s+${name}\\s*(?::[^=]*?)?=\\s*`);
+    const m = re.exec(src);
+    if (!m)
+        return null;
+    const start = m.index + m[0].length;
+    if (src[start] !== "{")
+        return null;
+    const end = scanBalancedLiteral(src, start);
+    return end === -1 ? null : src.slice(start, end);
+}
+/**
+ * PostHog's canonical docs nav is the single `export const docsMenu`
+ * object (its children are the product groups). The other object exports
+ * (`communityMenu`, `companyMenu`, `pricingMenu`, …) are the marketing
+ * nav — deliberately excluded.
+ */
+export function extractPosthogNav(sourceDir, hrefPrefix) {
+    const navFile = findNavModule(sourceDir);
+    if (!navFile)
+        return null;
+    const src = readFileSync(navFile, "utf-8");
+    const docsMenuSrc = captureExportObject(src, "docsMenu");
+    if (docsMenuSrc) {
+        const nav = objToNav(docsMenuSrc);
+        // Use its children (the product groups) as the top-level nav; if it
+        // has none, fall back to the docsMenu node itself.
+        const roots = nav?.children?.length ? nav.children : nav ? [nav] : [];
+        if (roots.length)
+            return toNavItems(roots, hrefPrefix);
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@dogsbay/adapter-posthog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.136",
+  "description": "PostHog site adapter for @dogsbay/format-gatsby — maps PostHog's MDX components to directives and extracts nav from src/navs/index.js.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dogsbay/format-gatsby": "0.2.0-beta.136",
+    "@dogsbay/format-mdx": "0.2.0-beta.136"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.