@open-agent-toolkit/docs-transforms 0.0.10 → 0.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Stang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -29,3 +29,8 @@ export const customRemarkPlugins = [remarkLinks, remarkTabs, remarkMermaid];
 - `remarkLinks`
 - `remarkMermaid`
 - `remarkTabs`
+
+## Docs
+
+- [Docs Tooling](https://voxmedia.github.io/open-agent-toolkit/docs-tooling)
+- [Repository](https://github.com/voxmedia/open-agent-toolkit)

package/dist/remark-links.d.ts

@@ -1,13 +1,15 @@
 import type { Root } from 'mdast';
 import type { Plugin } from 'unified';
 /**
- * Remark plugin that rewrites relative `.md` links to extensionless paths
- * for Fumadocs routing.
+ * Remark plugin that rewrites source-relative markdown links to routed,
+ * extensionless URLs that still work once pages are emitted with trailing
+ * slashes.
  *
  * URL rewriting:
- * - `quickstart.md` → `./quickstart`
- * - `cli/index.md` → `./cli`
- * - `../reference/index.md` → `../reference`
+ * - `quickstart.md` from `docs/index.md` → `./quickstart`
+ * - `documentation/commands.md` from `docs/guide/cli-reference.md`
+ *   → `../documentation/commands`
+ * - `../reference/index.md` from `docs/guide/concepts.md` → `../../reference`
  * - Absolute URLs and anchors are left unchanged.
  *
  * Display text cleanup:

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

@@ -1 +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"}
+{"version":3,"file":"remark-links.d.ts","sourceRoot":"","sources":["../src/remark-links.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoB,IAAI,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAmEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAyCxC,CAAC"}

package/dist/remark-links.js

@@ -1,12 +1,18 @@
+import { posix as path } from 'node:path';
 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.
+ * Strip markdown extension and collapse `/index` from a relative path.
+ * Returns null if the path is not a markdown link that should be rewritten.
  */
 function cleanMdPath(raw) {
-    if (!raw.endsWith('.md'))
+    const extension = raw.endsWith('.mdx')
+        ? '.mdx'
+        : raw.endsWith('.md')
+            ? '.md'
+            : null;
+    if (!extension)
         return null;
-    let cleaned = raw.slice(0, -3);
+    let cleaned = raw.slice(0, -extension.length);
     if (cleaned.endsWith('/index')) {
         cleaned = cleaned.slice(0, -'/index'.length) || '.';
     }
@@ -15,14 +21,49 @@ function cleanMdPath(raw) {
     }
     return cleaned;
 }
+function normalizeFsPath(raw) {
+    return raw.replaceAll('\\', '/');
+}
+function docsRelativeFilePath(filePath) {
+    const normalized = normalizeFsPath(filePath);
+    const marker = '/docs/';
+    const index = normalized.lastIndexOf(marker);
+    if (index === -1)
+        return null;
+    return normalized.slice(index + marker.length);
+}
+function routePathFromDocsFile(filePath) {
+    const cleaned = cleanMdPath(filePath);
+    if (cleaned === null)
+        return null;
+    if (cleaned === '.')
+        return '/';
+    return path.normalize(`/${cleaned}`);
+}
+function resolveRelativeDocsLink(sourceFilePath, targetPath) {
+    const sourceDocsFile = docsRelativeFilePath(sourceFilePath);
+    if (!sourceDocsFile)
+        return null;
+    const targetDocsFile = path
+        .normalize(path.join('/', path.dirname(sourceDocsFile), targetPath))
+        .slice(1);
+    const currentRoute = routePathFromDocsFile(sourceDocsFile);
+    const targetRoute = routePathFromDocsFile(targetDocsFile);
+    if (!currentRoute || !targetRoute)
+        return null;
+    const relativeRoute = path.relative(currentRoute, targetRoute) || '.';
+    return relativeRoute.startsWith('.') ? relativeRoute : `./${relativeRoute}`;
+}
 /**
- * Remark plugin that rewrites relative `.md` links to extensionless paths
- * for Fumadocs routing.
+ * Remark plugin that rewrites source-relative markdown links to routed,
+ * extensionless URLs that still work once pages are emitted with trailing
+ * slashes.
  *
  * URL rewriting:
- * - `quickstart.md` → `./quickstart`
- * - `cli/index.md` → `./cli`
- * - `../reference/index.md` → `../reference`
+ * - `quickstart.md` from `docs/index.md` → `./quickstart`
+ * - `documentation/commands.md` from `docs/guide/cli-reference.md`
+ *   → `../documentation/commands`
+ * - `../reference/index.md` from `docs/guide/concepts.md` → `../../reference`
  * - Absolute URLs and anchors are left unchanged.
  *
  * Display text cleanup:
@@ -32,7 +73,7 @@ function cleanMdPath(raw) {
  *   while rendering clean labels on the web.
  */
 export const remarkLinks = function remarkLinks() {
-    return (tree) => {
+    return (tree, file) => {
         visit(tree, 'link', (node) => {
             const { url } = node;
             // Skip absolute URLs, protocol links, and pure anchors
@@ -46,13 +87,14 @@ export const remarkLinks = function remarkLinks() {
             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;
+            const rewrittenPath = typeof file?.path === 'string'
+                ? (resolveRelativeDocsLink(file.path, path) ?? cleaned)
+                : cleaned;
             // Rewrite URL
-            const prefix = adjusted.startsWith('.') || adjusted.startsWith('/') ? '' : './';
-            node.url = prefix + adjusted + fragment;
+            const prefix = rewrittenPath.startsWith('.') || rewrittenPath.startsWith('/')
+                ? ''
+                : './';
+            node.url = prefix + rewrittenPath + 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') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/docs-transforms",
-  "version": "0.0.10",
+  "version": "0.0.18",
   "private": false,
   "description": "Remark/unified transforms for OAT documentation",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/docs-transforms",
@@ -29,19 +29,6 @@
   "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",
@@ -55,5 +42,18 @@
   },
   "engines": {
     "node": ">=22.17.0"
+  },
+  "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"
   }
-}
+}