docs: enhance markdown transformation with symbol link replacement

- Added `replaceSymbolLinks` to convert symbol tokens into markdown links.
- Introduced `loadSymbolIndex` for resolving symbols to their API paths using a cached index.
- Refactored imports and logic for improved maintainability.

Author: Romakita

docs/.vitepress/scripts/build-llm-contents.js

@@ -6,6 +6,11 @@ import {copyFiles} from "./llm/copy-files.js";
 import {buildReferenceSidebar} from "./llm/sidebar.js";
 
 const DOCS_ROOT = join(import.meta.dirname, "..", "..");
+/**
+ * Each entry describes a docs directory to copy into /public/ai.
+ * Markdown is normalized (remark), snippet directives are inlined,
+ * and @@Symbol@@ tokens are rewritten to /ai/api links.
+ */
 const DOC_SECTIONS = [
   {
     source: "guide",

docs/.vitepress/scripts/llm/markdown.js

@@ -11,13 +11,16 @@ const markdownProcessor = unified()
   .use(remarkStringify, {fences: true, bullet: "-"})
   .use(remarkCleanApiMarkdown);
 const INLINE_SNIPPET_RE = /^<<<\s+@\/([^\s]+?)(?:\s+\[(.+?)\])?\s*$/gm;
+const SYMBOL_TOKEN_RE = /@@([A-Za-z0-9_.-]+)@@/g;
+const symbolIndexCache = new Map();
 
 export async function transformMarkdown(content, options = {}) {
   const {docsRoot} = options;
   let nextContent = content;
 
   if (docsRoot) {
     nextContent = await inlineExampleBlocks(nextContent, docsRoot);
+    nextContent = await replaceSymbolLinks(nextContent, docsRoot);
   }
 
   const {frontmatter, body} = extractFrontmatter(nextContent);
@@ -57,6 +60,41 @@ async function inlineExampleBlocks(content, docsRoot) {
   return result;
 }
 
+async function replaceSymbolLinks(content, docsRoot) {
+  const index = await loadSymbolIndex(docsRoot);
+  return content.replace(SYMBOL_TOKEN_RE, (match, symbolName) => {
+    const entry = index.get(symbolName);
+
+    if (!entry) {
+      console.warn(`[build-llm-contents] Unable to resolve symbol ${symbolName}`);
+      return match;
+    }
+
+    return `[${symbolName}](/ai${entry.path}.md)`;
+  });
+}
+
+async function loadSymbolIndex(docsRoot) {
+  if (symbolIndexCache.has(docsRoot)) {
+    return symbolIndexCache.get(docsRoot);
+  }
+
+  const apiPath = join(docsRoot, "public/api.json");
+  const data = JSON.parse(await readFile(apiPath, "utf8"));
+  const map = new Map();
+
+  Object.values(data.modules ?? {}).forEach((module) => {
+    module.symbols?.forEach((symbol) => {
+      if (symbol.symbolName && symbol.path) {
+        map.set(symbol.symbolName, symbol);
+      }
+    });
+  });
+
+  symbolIndexCache.set(docsRoot, map);
+  return map;
+}
+
 async function loadSnippetBlock(entry, docsRoot) {
   const absolutePath = join(docsRoot, entry.relativePath);