@open-agent-toolkit/docs-transforms 0.0.10

package/README.md

@@ -0,0 +1,31 @@
+# @open-agent-toolkit/docs-transforms
+
+Remark plugins and default transform bundle for OAT-powered Fumadocs apps.
+
+## Install
+
+```bash
+pnpm add @open-agent-toolkit/docs-transforms
+```
+
+## Usage
+
+```ts
+import {
+  defaultTransforms,
+  remarkLinks,
+  remarkMermaid,
+  remarkTabs,
+} from '@open-agent-toolkit/docs-transforms';
+
+export const remarkPlugins = defaultTransforms;
+
+export const customRemarkPlugins = [remarkLinks, remarkTabs, remarkMermaid];
+```
+
+## Exports
+
+- `defaultTransforms`
+- `remarkLinks`
+- `remarkMermaid`
+- `remarkTabs`

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+export { remarkLinks } from './remark-links.js';
+export { remarkMermaid } from './remark-mermaid.js';
+export { remarkTabs } from './remark-tabs.js';
+export declare const defaultTransforms: Plugin<[], Root>[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAMtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,EAI/C,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import { remarkLinks } from './remark-links.js';
+import { remarkMermaid } from './remark-mermaid.js';
+import { remarkTabs } from './remark-tabs.js';
+export { remarkLinks } from './remark-links.js';
+export { remarkMermaid } from './remark-mermaid.js';
+export { remarkTabs } from './remark-tabs.js';
+export const defaultTransforms = [
+    remarkLinks,
+    remarkTabs,
+    remarkMermaid,
+];

package/dist/remark-links.d.ts

@@ -0,0 +1,20 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+/**
+ * Remark plugin that rewrites relative `.md` links to extensionless paths
+ * for Fumadocs routing.
+ *
+ * URL rewriting:
+ * - `quickstart.md` → `./quickstart`
+ * - `cli/index.md` → `./cli`
+ * - `../reference/index.md` → `../reference`
+ * - Absolute URLs and anchors are left unchanged.
+ *
+ * Display text cleanup:
+ * - When a link's only child is an `inlineCode` node whose value looks like
+ *   a `.md` path (e.g., `` [`cli/index.md`](cli/index.md) ``), the extension
+ *   is stripped from the display text too, keeping the raw markdown AI-navigable
+ *   while rendering clean labels on the web.
+ */
+export declare const remarkLinks: Plugin<[], Root>;
+//# sourceMappingURL=remark-links.d.ts.map

package/dist/remark-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark-links.d.ts","sourceRoot":"","sources":["../src/remark-links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,IAAI,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAsBtC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAuCxC,CAAC"}

package/dist/remark-links.js

@@ -0,0 +1,67 @@
+import { visit } from 'unist-util-visit';
+/**
+ * Strip `.md` extension and collapse `/index` from a relative path.
+ * Returns null if the path is not a `.md` link that should be rewritten.
+ */
+function cleanMdPath(raw) {
+    if (!raw.endsWith('.md'))
+        return null;
+    let cleaned = raw.slice(0, -3);
+    if (cleaned.endsWith('/index')) {
+        cleaned = cleaned.slice(0, -'/index'.length) || '.';
+    }
+    if (cleaned === 'index') {
+        cleaned = '.';
+    }
+    return cleaned;
+}
+/**
+ * Remark plugin that rewrites relative `.md` links to extensionless paths
+ * for Fumadocs routing.
+ *
+ * URL rewriting:
+ * - `quickstart.md` → `./quickstart`
+ * - `cli/index.md` → `./cli`
+ * - `../reference/index.md` → `../reference`
+ * - Absolute URLs and anchors are left unchanged.
+ *
+ * Display text cleanup:
+ * - When a link's only child is an `inlineCode` node whose value looks like
+ *   a `.md` path (e.g., `` [`cli/index.md`](cli/index.md) ``), the extension
+ *   is stripped from the display text too, keeping the raw markdown AI-navigable
+ *   while rendering clean labels on the web.
+ */
+export const remarkLinks = function remarkLinks() {
+    return (tree) => {
+        visit(tree, 'link', (node) => {
+            const { url } = node;
+            // Skip absolute URLs, protocol links, and pure anchors
+            if (/^[a-z]+:/i.test(url) || url.startsWith('#')) {
+                return;
+            }
+            // Split off any anchor fragment
+            const hashIndex = url.indexOf('#');
+            const path = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+            const fragment = hashIndex >= 0 ? url.slice(hashIndex) : '';
+            const cleaned = cleanMdPath(path);
+            if (cleaned === null)
+                return;
+            // With trailingSlash enabled, each page URL has an extra directory level
+            // (e.g., /guide/commands/ instead of /guide/commands), so ../ links need
+            // one additional ../ to reach the correct parent.
+            const adjusted = cleaned.startsWith('..') ? `../${cleaned}` : cleaned;
+            // Rewrite URL
+            const prefix = adjusted.startsWith('.') || adjusted.startsWith('/') ? '' : './';
+            node.url = prefix + adjusted + fragment;
+            // Clean display text when it's a single inlineCode child with a .md path
+            const firstChild = node.children[0];
+            if (node.children.length === 1 && firstChild?.type === 'inlineCode') {
+                const code = firstChild;
+                const cleanedText = cleanMdPath(code.value);
+                if (cleanedText !== null) {
+                    code.value = cleanedText;
+                }
+            }
+        });
+    };
+};

package/dist/remark-mermaid.d.ts

@@ -0,0 +1,13 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+/**
+ * Remark plugin that transforms fenced code blocks with `lang: "mermaid"`
+ * into `<Mermaid chart="...">` MDX JSX elements.
+ *
+ * Replaces literal `\n` sequences with `<br/>` since mermaid flowcharts
+ * use HTML break tags for line breaks within node labels.
+ *
+ * Paired with the `Mermaid` component from `@open-agent-toolkit/docs-theme` for client-side rendering.
+ */
+export declare const remarkMermaid: Plugin<[], Root>;
+//# sourceMappingURL=remark-mermaid.d.ts.map

package/dist/remark-mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark-mermaid.d.ts","sourceRoot":"","sources":["../src/remark-mermaid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,IAAI,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGtC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CA0B1C,CAAC"}

package/dist/remark-mermaid.js

@@ -0,0 +1,34 @@
+import { visit } from 'unist-util-visit';
+/**
+ * Remark plugin that transforms fenced code blocks with `lang: "mermaid"`
+ * into `<Mermaid chart="...">` MDX JSX elements.
+ *
+ * Replaces literal `\n` sequences with `<br/>` since mermaid flowcharts
+ * use HTML break tags for line breaks within node labels.
+ *
+ * Paired with the `Mermaid` component from `@open-agent-toolkit/docs-theme` for client-side rendering.
+ */
+export const remarkMermaid = function remarkMermaid() {
+    return (tree) => {
+        visit(tree, 'code', (node, index, parent) => {
+            if (node.lang !== 'mermaid' || index === undefined || !parent) {
+                return;
+            }
+            const chart = node.value.replace(/\\n/g, '<br/>');
+            const jsxNode = {
+                type: 'mdxJsxFlowElement',
+                name: 'Mermaid',
+                attributes: [
+                    {
+                        type: 'mdxJsxAttribute',
+                        name: 'chart',
+                        value: chart,
+                    },
+                ],
+                children: [],
+                data: { _mdxExplicitJsx: true },
+            };
+            parent.children[index] = jsxNode;
+        });
+    };
+};

package/dist/remark-tabs.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+export declare const remarkTabs: Plugin<[], Root>;
+//# sourceMappingURL=remark-tabs.d.ts.map

package/dist/remark-tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark-tabs.d.ts","sourceRoot":"","sources":["../src/remark-tabs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,IAAI,EAAe,MAAM,OAAO,CAAC;AAEhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAwCtC,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAyCvC,CAAC"}

package/dist/remark-tabs.js

@@ -0,0 +1,65 @@
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+const TAB_MARKER_RE = /^===\s+"(.+)"$/;
+function extractTabTitle(node) {
+    if (node.type !== 'paragraph')
+        return null;
+    const paragraph = node;
+    const firstChild = paragraph.children[0];
+    if (!firstChild || firstChild.type !== 'text')
+        return null;
+    const match = TAB_MARKER_RE.exec(firstChild.value);
+    return match?.[1] ?? null;
+}
+function reparseContent(value) {
+    const tree = unified().use(remarkParse).parse(value);
+    return tree.children;
+}
+function createTabsElement(tabs) {
+    return {
+        type: 'mdxJsxFlowElement',
+        name: 'Tabs',
+        attributes: [],
+        children: tabs.map((tab) => ({
+            type: 'mdxJsxFlowElement',
+            name: 'Tab',
+            attributes: [
+                { type: 'mdxJsxAttribute', name: 'title', value: tab.title },
+            ],
+            children: tab.content,
+        })),
+    };
+}
+export const remarkTabs = () => (tree) => {
+    const newChildren = [];
+    let i = 0;
+    while (i < tree.children.length) {
+        const node = tree.children[i];
+        const title = extractTabTitle(node);
+        if (title === null) {
+            newChildren.push(node);
+            i++;
+            continue;
+        }
+        // Collect consecutive tabs into a group
+        const tabs = [];
+        while (i < tree.children.length) {
+            const current = tree.children[i];
+            const currentTitle = extractTabTitle(current);
+            if (currentTitle === null)
+                break;
+            i++; // advance past tab marker
+            // Check if next node is an indented code block (tab content)
+            const content = [];
+            if (i < tree.children.length && tree.children[i].type === 'code') {
+                const codeBlock = tree.children[i];
+                // Re-parse the code block value as markdown to restore original structure
+                content.push(...reparseContent(codeBlock.value));
+                i++;
+            }
+            tabs.push({ title: currentTitle, content });
+        }
+        newChildren.push(createTabsElement(tabs));
+    }
+    tree.children = newChildren;
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@open-agent-toolkit/docs-transforms",
+  "version": "0.0.10",
+  "private": false,
+  "description": "Remark/unified transforms for OAT documentation",
+  "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/docs-transforms",
+  "bugs": {
+    "url": "https://github.com/voxmedia/open-agent-toolkit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voxmedia/open-agent-toolkit.git",
+    "directory": "packages/docs-transforms"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "check": "oxlint . && oxfmt --check .",
+    "check:fix": "oxlint --fix . && oxfmt .",
+    "format": "oxfmt --check .",
+    "format:fix": "oxfmt .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.17.0"
+  }
+}