docs: surface related links on API pages

Closes #152

Author: johnleider

apps/docs/build/frontmatter.ts

@@ -15,6 +15,7 @@ export interface Frontmatter {
     emphasized?: boolean
     devmode?: boolean
   }
+  related?: string[]
 }
 
 export interface ParseResult {
@@ -45,22 +46,30 @@ export function parseFrontmatter (content: string): ParseResult {
   const lines = frontmatterStr.split('\n')
   let inFeatures = false
   let inMeta = false
+  let inRelated = false
   let currentMetaName = ''
   const features: NonNullable<Frontmatter['features']> = {}
+  const related: string[] = []
 
   for (const line of lines) {
     const trimmed = line.trim()
     if (!trimmed) continue
 
     // Check if we're entering/exiting a nested block
-    // Allow '-' prefix for YAML array items within meta block
+    // Allow '-' prefix for YAML array items within meta/related blocks
     if (!line.startsWith(' ') && !line.startsWith('\t') && !line.startsWith('-')) {
       inFeatures = false
       inMeta = false
+      inRelated = false
     }
 
     if (trimmed.startsWith('title:')) {
       frontmatter.title = trimmed.slice(6).trim().replace(/^['"]|['"]$/g, '')
+    } else if (trimmed === 'related:') {
+      inRelated = true
+    } else if (inRelated && trimmed.startsWith('- ')) {
+      const value = trimmed.slice(2).trim().replace(/^['"]|['"]$/g, '')
+      if (value) related.push(value)
     } else if (trimmed === 'meta:') {
       inMeta = true
     } else if (inMeta) {
@@ -95,6 +104,10 @@ export function parseFrontmatter (content: string): ParseResult {
     frontmatter.features = features
   }
 
+  if (related.length > 0) {
+    frontmatter.related = related
+  }
+
   return { frontmatter, body }
 }
 

apps/docs/build/generate-api.ts

@@ -8,8 +8,8 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { readdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
+import { glob, readdir } from 'node:fs/promises'
+import { basename, dirname, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { Node, Project } from 'ts-morph'
@@ -19,10 +19,14 @@ import { createChecker } from 'vue-component-meta'
 import type { InterfaceDeclaration, JSDocableNode, TypeAliasDeclaration } from 'ts-morph'
 import type { Plugin } from 'vite'
 
+import { toCamel, toPascal } from './api-names'
+import { parseFrontmatter } from './frontmatter'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = resolve(__dirname, '../../..')
 const COMPONENTS_DIR = resolve(ROOT, 'packages/0/src/components')
 const COMPOSABLES_DIR = resolve(ROOT, 'packages/0/src/composables')
+const PAGES_DIR = resolve(__dirname, '../src/pages')
 const TSCONFIG = resolve(ROOT, 'tsconfig.json')
 const PACKAGE_TSCONFIG = resolve(ROOT, 'packages/0/tsconfig.json')
 
@@ -781,13 +785,63 @@ async function generateComposableApis (): Promise<Record<string, ComposableApi>>
   return apis
 }
 
+// ============================================================================
+// Related Links (from docs page frontmatter)
+// ============================================================================
+
+/**
+ * Scan composable/component markdown pages and build a map of API name →
+ * related URLs. The list is the counterpart doc page prepended to its own
+ * `related` frontmatter entries, so API pages can surface both the counterpart
+ * itself and the counterpart's cross-links.
+ */
+async function generateRelatedMap (
+  components: Record<string, ComponentApi>,
+  composables: Record<string, ComposableApi>,
+): Promise<Record<string, string[]>> {
+  const related: Record<string, string[]> = {}
+  const componentNames = new Set(Object.keys(components).map(key => key.split('.')[0]))
+
+  const patterns = [
+    `${PAGES_DIR}/composables/**/*.md`,
+    `${PAGES_DIR}/components/**/*.md`,
+  ]
+
+  for (const pattern of patterns) {
+    for await (const file of glob(pattern)) {
+      const name = basename(file, '.md')
+      if (name === 'index') continue
+
+      const isComposable = file.includes(`${PAGES_DIR}/composables/`)
+      const apiName = isComposable ? toCamel(name) : toPascal(name)
+
+      if (isComposable && !(apiName in composables)) continue
+      if (!isComposable && !componentNames.has(apiName)) continue
+
+      let raw: string
+      try {
+        raw = readFileSync(file, 'utf8')
+      } catch {
+        continue
+      }
+
+      const { frontmatter } = parseFrontmatter(raw)
+      const urlPath = '/' + relative(PAGES_DIR, file).replace(/\.md$/, '').replaceAll('\\', '/')
+      related[apiName] = [urlPath, ...(frontmatter.related ?? [])]
+    }
+  }
+
+  return related
+}
+
 // ============================================================================
 // Plugin
 // ============================================================================
 
 export interface ApiData {
   components: Record<string, ComponentApi>
   composables: Record<string, ComposableApi>
+  related: Record<string, string[]>
 }
 
 export default function generateApiPlugin (): Plugin {
@@ -800,9 +854,13 @@ export default function generateApiPlugin (): Plugin {
     // Try to read from cache first (SSR build reuses client build cache)
     if (existsSync(API_CACHE_FILE)) {
       try {
-        apiData = JSON.parse(readFileSync(API_CACHE_FILE, 'utf8')) as ApiData
-        console.log(`[generate-api] Loaded API from cache`)
-        return apiData
+        const cached = JSON.parse(readFileSync(API_CACHE_FILE, 'utf8')) as Partial<ApiData>
+        // Invalidate caches written before the `related` field existed.
+        if (cached.components && cached.composables && cached.related) {
+          apiData = cached as ApiData
+          console.log(`[generate-api] Loaded API from cache`)
+          return apiData
+        }
       } catch {
         // Cache read failed, regenerate
       }
@@ -815,7 +873,8 @@ export default function generateApiPlugin (): Plugin {
             generateComponentApis(),
             generateComposableApis(),
           ])
-          const data = { components, composables }
+          const related = await generateRelatedMap(components, composables)
+          const data: ApiData = { components, composables, related }
           // Write to cache for subsequent builds (SSR reuses this)
           try {
             mkdirSync(API_CACHE_DIR, { recursive: true })

apps/docs/src/pages/api/[name].vue

@@ -42,6 +42,10 @@
   })
   const isComposable = toRef(() => itemName.value && itemName.value in data.composables)
 
+  const relatedFrontmatter = toRef(() => ({
+    related: itemName.value ? data.related[itemName.value] ?? [] : [],
+  }))
+
   const componentApis = computed<ComponentApi[]>(() => {
     if (!isComponent.value || !itemName.value) return []
 
@@ -123,6 +127,8 @@
 
         <p class="lead">API reference for the {{ itemName }} component{{ componentApis.length > 1 ? 's' : '' }}.</p>
 
+        <DocsRelated :frontmatter="relatedFrontmatter" />
+
         <template
           v-for="api in componentApis"
           :key="api.name"
@@ -191,6 +197,8 @@
 
         <p class="lead">API reference for the {{ composableApi.name }} composable.</p>
 
+        <DocsRelated :frontmatter="relatedFrontmatter" />
+
         <template v-if="composableApi.functions?.length">
           <DocsHeaderAnchor
             id="functions"