@movk/nuxt-docs 1.13.0 → 1.14.0

package/server/api/github/{commits.get.ts → commits.json.get.ts}

@@ -24,20 +24,23 @@ export default defineCachedEventHandler(async (event) => {
     })
   }
 
-  const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
+  const octokit = new Octokit({
+    auth: process.env.NUXT_GITHUB_TOKEN,
+    request: { timeout: 10_000 }
+  })
 
   const allCommits = await Promise.all(
     paths.map(path =>
-      octokit.paginate(octokit.rest.repos.listCommits, {
+      octokit.rest.repos.listCommits({
         sha: github.branch,
         owner: github.owner,
         repo: github.name,
         path,
         since: github.since,
-        per_page: github.per_page,
+        per_page: github.per_page || 100,
         until: github.until,
         author
-      })
+      }).then(res => res.data).catch(() => [])
     )
   )
 

package/server/api/github/{last-commit.get.ts → last-commit.json.get.ts}

@@ -22,16 +22,19 @@ export default defineCachedEventHandler(async (event) => {
     })
   }
 
-  const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
+  const octokit = new Octokit({
+    auth: process.env.NUXT_GITHUB_TOKEN,
+    request: { timeout: 10_000 }
+  })
 
   try {
-    const { data: commits } = await octokit.rest.repos.listCommits({
+    const commits = await octokit.rest.repos.listCommits({
       sha: github.branch,
       owner: github.owner,
       repo: github.name,
       path,
       per_page: 1
-    })
+    }).then(res => res.data).catch(() => [])
 
     if (!commits.length) {
       return null
@@ -54,16 +57,16 @@ export default defineCachedEventHandler(async (event) => {
         // 从 squash commit message 中提取 PR 编号 (#166)
         const prMatch = commit.commit.message.match(/#(\d+)/)
         if (prMatch?.[1]) {
-          const { data: prData } = await octokit.rest.pulls.get({
+          const prData = await octokit.rest.pulls.get({
             owner: github.owner,
             repo: github.name,
             pull_number: Number.parseInt(prMatch[1])
-          })
+          }).then(res => res.data).catch(() => null)
 
-          authorLogin = prData.user?.login ?? authorLogin
-          authorAvatar = prData.user?.avatar_url ?? authorAvatar
-          authorName = prData.user?.name || authorLogin
-          commitUrl = prData.html_url
+          authorLogin = prData?.user?.login ?? authorLogin
+          authorAvatar = prData?.user?.avatar_url ?? authorAvatar
+          authorName = prData?.user?.name || authorLogin
+          commitUrl = prData?.html_url ?? commitUrl
         }
       } catch {
         // 获取 PR 信息失败时忽略，使用原始提交者信息

package/server/api/github/releases.json.get.ts

@@ -0,0 +1,28 @@
+import { Octokit } from '@octokit/rest'
+
+export default defineCachedEventHandler(async () => {
+  if (!process.env.NUXT_GITHUB_TOKEN) {
+    return []
+  }
+
+  const { github } = useAppConfig()
+
+  if (!github || typeof github === 'boolean') {
+    throw createError({
+      status: 500,
+      statusText: 'GitHub configuration is not available'
+    })
+  }
+
+  const octokit = new Octokit({ auth: process.env.NUXT_GITHUB_TOKEN })
+
+  const releases = await octokit.rest.repos.listReleases({
+    owner: github.owner,
+    repo: github.name
+  }).then(res => res.data).catch(() => [])
+
+  return releases
+}, {
+  maxAge: 60 * 60,
+  getKey: () => 'releases'
+})

package/server/mcp/resources/documentation-pages.ts

@@ -0,0 +1,26 @@
+import { queryCollection } from '@nuxt/content/server'
+
+export default defineMcpResource({
+  uri: 'resource://docs/documentation-pages',
+  description: '所有可用文档页面的完整列表',
+  cache: '1h',
+  async handler(uri: URL) {
+    const event = useEvent()
+
+    const pages = await queryCollection(event, 'docs').all()
+
+    const result = pages.map(doc => ({
+      title: doc.title,
+      description: doc.description,
+      path: doc.path
+    }))
+
+    return {
+      contents: [{
+        uri: uri.toString(),
+        mimeType: 'application/json',
+        text: JSON.stringify(result, null, 2)
+      }]
+    }
+  }
+})

package/server/mcp/resources/examples.ts

@@ -0,0 +1,17 @@
+// @ts-expect-error - no types available
+import { listComponentExamples } from '#component-example/nitro'
+
+export default defineMcpResource({
+  uri: 'resource://docs/examples',
+  description: '所有可用示例代码和演示的完整列表',
+  cache: '1h',
+  async handler(uri: URL) {
+    return {
+      contents: [{
+        uri: uri.toString(),
+        mimeType: 'application/json',
+        text: JSON.stringify(await listComponentExamples(), null, 2)
+      }]
+    }
+  }
+})

package/server/mcp/tools/get-example.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
 export default defineMcpTool({
-  description: '检索特定的 UI 示例实现代码和详细信息',
+  description: '检索特定的示例实现代码和详细信息',
   inputSchema: {
     exampleName: z.string().describe('示例名称（PascalCase）')
   },

package/server/mcp/tools/list-examples.ts

@@ -1,14 +1,10 @@
 // @ts-expect-error - no types available
-import components from '#component-example/nitro'
+import { listComponentExamples } from '#component-example/nitro'
 
 export default defineMcpTool({
-  description: '列出所有可用的 UI 示例和代码演示',
+  description: '列出所有可用的示例和代码演示',
   cache: '1h',
-  handler() {
-    const examples = Object.entries<{ pascalName: string }>(components).map(([_key, value]) => {
-      return value.pascalName
-    })
-
-    return jsonResult(examples)
+  async handler() {
+    return jsonResult(await listComponentExamples())
   }
 })

package/server/mcp/tools/list-getting-started-guides.ts

@@ -0,0 +1,29 @@
+import { queryCollection } from '@nuxt/content/server'
+import { inferSiteURL } from '../../../utils/meta'
+
+export default defineMcpTool({
+  description: '列出所有入门指南和安装说明',
+  cache: '30m',
+  async handler() {
+    const event = useEvent()
+    const siteUrl = import.meta.dev
+      ? getRequestURL(event).origin
+      : inferSiteURL()
+
+    const pages = await queryCollection(event, 'docs')
+      .where('path', 'LIKE', '/docs/getting-started/%')
+      .where('extension', '=', 'md')
+      .select('id', 'title', 'description', 'path', 'navigation')
+      .all()
+
+    const result = pages.map(page => ({
+      title: page.title,
+      description: page.description,
+      path: page.path,
+      url: `${siteUrl}${page.path}`,
+      navigation: page.navigation
+    })).sort((a, b) => a.path.localeCompare(b.path))
+
+    return jsonResult(result)
+  }
+})

package/server/routes/raw/[...slug].md.get.ts

@@ -1,15 +1,13 @@
 import { withLeadingSlash } from 'ufo'
-import { stringify } from 'minimark/stringify'
 import { queryCollection } from '@nuxt/content/server'
 import type { Collections, PageCollectionItemBase } from '@nuxt/content'
 import { getRouterParams, eventHandler, createError, setHeader } from 'h3'
 import collections from '#content/manifest'
-import { transformMDC } from '../../utils/transformMDC'
 
 export default eventHandler(async (event) => {
   const slug = getRouterParams(event)['slug.md']
   if (!slug?.endsWith('.md')) {
-    throw createError({ status: 404, statusText: 'Page not found', fatal: true })
+    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
   }
 
   let path = withLeadingSlash(slug.replace('.md', ''))
@@ -30,7 +28,7 @@ export default eventHandler(async (event) => {
   }
 
   if (!page) {
-    throw createError({ status: 404, statusText: 'Page not found', fatal: true })
+    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
   }
 
   // Transform MDC components to standard elements for LLM consumption
@@ -43,5 +41,5 @@ export default eventHandler(async (event) => {
   }
 
   setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
-  return stringify({ ...page.body, type: 'minimark' }, { format: 'markdown/html' })
+  return stringifyMinimark(page.body)
 })

package/server/utils/stringifyMinimark.ts

@@ -0,0 +1,345 @@
+type MinimarkNode = string | [string, Record<string, any>, ...MinimarkNode[]]
+
+const BLOCK_SEP = '\n\n'
+
+const SELF_CLOSE_TAGS = new Set(['br', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'])
+const INLINE_TAGS = new Set(['strong', 'em', 'code', 'a', 'br', 'span', 'img', 'b', 'i', 's', 'del', 'sub', 'sup', 'mark', 'abbr', 'kbd'])
+
+// --- HTML attribute serialization ---
+
+function htmlAttributes(attributes: Record<string, any>): string {
+  return Object.entries(attributes).map(([key, value]) => {
+    if (typeof value === 'object') return `${key}="${JSON.stringify(value).replace(/"/g, '\\"')}"`
+    return `${key}="${value}"`
+  }).join(' ')
+}
+
+// --- HTML fallback for unknown tags ---
+
+function toHtml(_node: MinimarkNode[], state: State, tag: string, attrs: Record<string, any>, children: MinimarkNode[]): string {
+  const attrStr = Object.keys(attrs).length > 0 ? ` ${htmlAttributes(attrs)}` : ''
+
+  if (SELF_CLOSE_TAGS.has(tag)) {
+    return `<${tag}${attrStr} />`
+  }
+
+  const hasOnlyInline = children.every(c => typeof c === 'string' || INLINE_TAGS.has(String((c as any[])[0])))
+  const content = children.map(c => stringify(c, state)).join('')
+
+  if (hasOnlyInline) {
+    return `<${tag}${attrStr}>${content}</${tag}>`
+  }
+
+  return `<${tag}${attrStr}>\n${content}\n</${tag}>`
+}
+
+// --- Escape helpers ---
+
+function escapePipes(text: string): string {
+  return text.split('\n').join(' ').split('|').join('\\|')
+}
+
+function escapeLeadingNumberDot(str: string): string {
+  const match = /^(\d+)\./.exec(str)
+  if (match) return `${match[1]}\\.${str.slice(match[0].length)}`
+  return str
+}
+
+// --- State ---
+
+interface State {
+  listDepth: number
+  olIndex: number
+}
+
+function createState(): State {
+  return { listDepth: 0, olIndex: 0 }
+}
+
+// --- Inline helpers ---
+
+function flow(children: MinimarkNode[], state: State): string {
+  return children.map(c => stringify(c, state)).join('')
+}
+
+function indent(text: string, level: number): string {
+  const prefix = '  '.repeat(level)
+  return text.split('\n').map((line, i) => i === 0 ? line : (line ? prefix + line : line)).join('\n')
+}
+
+// --- Node handlers ---
+
+function stringify(node: MinimarkNode, state: State): string {
+  if (typeof node === 'string') return node
+
+  const [tag, attrs, ...children] = node
+
+  // Headings
+  const headingMatch = /^h([1-6])$/.exec(tag)
+  if (headingMatch) {
+    const level = Number(headingMatch[1])
+    return `${'#'.repeat(level)} ${flow(children, state)}${BLOCK_SEP}`
+  }
+
+  switch (tag) {
+    case 'p':
+      return `${flow(children, state)}${BLOCK_SEP}`
+
+    case 'blockquote':
+      return `${flow(children, state).trim().split('\n').map(l => `> ${l}`).join('\n')}${BLOCK_SEP}`
+
+    case 'pre': {
+      const lang = attrs?.language || ''
+      const code = attrs?.code ?? flow(children, state)
+      const filename = attrs?.filename ? ` [${String(attrs.filename).replace(/\]/g, '\\]')}]` : ''
+      const highlights = Array.isArray(attrs?.highlights) ? ` {${formatHighlights(attrs.highlights)}}` : ''
+      const meta = attrs?.meta ? ` ${attrs.meta}` : ''
+      return `\`\`\`${lang}${filename}${highlights}${meta}\n${String(code).trim()}\n\`\`\`${BLOCK_SEP}`
+    }
+
+    case 'code': {
+      const content = flow(children, state)
+      const fence = content.includes('`') ? '``' : '`'
+      return `${fence}${content}${fence}`
+    }
+
+    case 'strong':
+    case 'b':
+      return `**${flow(children, state).trim()}**`
+
+    case 'em':
+    case 'i':
+      return `*${flow(children, state).trim()}*`
+
+    case 'del':
+    case 's':
+      return `~~${flow(children, state).trim()}~~`
+
+    case 'a': {
+      const { href, ...rest } = attrs || {}
+      const attrsStr = Object.keys(rest).length > 0 ? `{${Object.entries(rest).map(([k, v]) => `${k}="${v}"`).join(' ')}}` : ''
+      return `[${flow(children, state)}](${href || ''})${attrsStr}`
+    }
+
+    case 'img': {
+      const { src, alt, title } = attrs || {}
+      return title
+        ? `![${alt || ''}](${src || ''} "${title}")`
+        : `![${alt || ''}](${src || ''})`
+    }
+
+    case 'br':
+      return '  \n'
+
+    case 'hr':
+      return `---${BLOCK_SEP}`
+
+    case 'ul': {
+      const prevDepth = state.listDepth
+      const childState = { ...state, listDepth: state.listDepth + 1 }
+      let result = children.map(c => stringifyLi(c, childState, false, 0)).join('')
+      if (prevDepth > 0) {
+        result = '\n' + result.split('\n').map(l => l ? '  ' + l : l).join('\n')
+      } else {
+        result = result + '\n'
+      }
+      state.listDepth = prevDepth
+      return result
+    }
+
+    case 'ol': {
+      const prevDepth = state.listDepth
+      const childState = { ...state, listDepth: state.listDepth + 1 }
+      let idx = 1
+      let result = children.map((c) => {
+        const r = stringifyLi(c, childState, true, idx)
+        idx++
+        return r
+      }).join('')
+      if (prevDepth > 0) {
+        result = '\n' + result.split('\n').map(l => l ? '  ' + l : l).join('\n')
+      } else {
+        result = result + '\n'
+      }
+      state.listDepth = prevDepth
+      return result
+    }
+
+    case 'li':
+      return stringifyLi(node, state, false, 0)
+
+    case 'table':
+      return stringifyTable(children, state)
+
+    // Strip style elements (typically last child in document)
+    case 'style':
+      return ''
+
+    // Slot templates
+    case 'template': {
+      const name = attrs?.name || 'default'
+      const content = flow(children, state).trim()
+      return `#${name}\n${content}${BLOCK_SEP}`
+    }
+
+    default:
+      return toHtml(node as any, state, tag, attrs, children)
+  }
+}
+
+// --- List item ---
+
+function stringifyLi(node: MinimarkNode, state: State, ordered: boolean, index: number): string {
+  if (typeof node === 'string') return node
+
+  const [, attrs, ...children] = node
+  const className = Array.isArray(attrs?.className)
+    ? attrs.className.join(' ')
+    : String(attrs?.className || attrs?.class || '')
+
+  let prefix = ordered ? `${index}. ` : '- '
+
+  // Task list support
+  if (className.includes('task-list-item') && children.length > 0) {
+    const first = children[0]
+    if (Array.isArray(first) && first[0] === 'input') {
+      const checked = first[1]?.checked || first[1]?.[':checked']
+      prefix += checked ? '[x] ' : '[ ] '
+      children.shift()
+    }
+  }
+
+  let content = flow(children, state).trim()
+  if (!ordered) content = escapeLeadingNumberDot(content)
+
+  return `${prefix}${indent(content, prefix.length / 2)}\n`
+}
+
+// --- Table ---
+
+function getAlignment(attributes: Record<string, any>): 'left' | 'center' | 'right' | null {
+  const style = attributes?.style
+  if (typeof style !== 'string') return null
+  const normalized = style.toLowerCase().replace(/\s/g, '')
+  if (normalized.includes('text-align:left')) return 'left'
+  if (normalized.includes('text-align:center')) return 'center'
+  if (normalized.includes('text-align:right')) return 'right'
+  return null
+}
+
+function getCellContent(cell: MinimarkNode, state: State): string {
+  if (typeof cell === 'string') return escapePipes(cell)
+  const [, , ...children] = cell
+  return escapePipes(children.map(c => stringify(c, state)).join('').trim())
+}
+
+function getRows(element: MinimarkNode): MinimarkNode[] {
+  if (typeof element === 'string') return []
+  const [tag, , ...children] = element
+  if (tag === 'tr') return [element]
+  if (tag === 'thead' || tag === 'tbody') return children.filter(c => typeof c !== 'string' && (c as any[])[0] === 'tr')
+  return []
+}
+
+function getCells(row: MinimarkNode): MinimarkNode[] {
+  if (typeof row === 'string') return []
+  const [, , ...children] = row
+  return children.filter(c => typeof c !== 'string' && ((c as any[])[0] === 'th' || (c as any[])[0] === 'td'))
+}
+
+function stringifyTable(children: MinimarkNode[], state: State): string {
+  let headerRows: MinimarkNode[] = []
+  let bodyRows: MinimarkNode[] = []
+
+  for (const child of children) {
+    if (typeof child === 'string') continue
+    const [tag] = child
+    if (tag === 'thead') headerRows = getRows(child)
+    else if (tag === 'tbody') bodyRows = getRows(child)
+    else if (tag === 'tr') {
+      const cells = getCells(child)
+      if (cells.length > 0 && (cells[0] as any[])[0] === 'th') headerRows.push(child)
+      else bodyRows.push(child)
+    }
+  }
+
+  // Auto-generate header if missing
+  if (headerRows.length === 0 && bodyRows.length > 0) {
+    const firstRow = bodyRows[0]!
+    const cellCount = getCells(firstRow).length
+    headerRows = [['tr', {}, ...Array.from({ length: cellCount }, (_, i) => ['th', {}, `Column ${i + 1}`])] as any]
+  }
+
+  if (headerRows.length === 0) return ''
+
+  const headerRow = headerRows[0]!
+  const headerCells = getCells(headerRow)
+  const headerContent = headerCells.map(c => getCellContent(c, state))
+  const alignments = headerCells.map(c => typeof c !== 'string' ? getAlignment((c as any[])[1] || {}) : null)
+
+  // Calculate column widths
+  const colWidths = headerContent.map(c => Math.max(3, c.length))
+  for (const row of bodyRows) {
+    getCells(row).forEach((cell, i) => {
+      if (i < colWidths.length) {
+        colWidths[i] = Math.max(colWidths[i]!, getCellContent(cell, state).length)
+      }
+    })
+  }
+
+  // Build header
+  let result = '| ' + headerContent.map((c, i) => c.padEnd(colWidths[i]!)).join(' | ') + ' |\n'
+
+  // Build separator with alignment
+  result += '| ' + colWidths.map((w, i) => {
+    const a = alignments[i]
+    if (a === 'left') return ':' + '-'.repeat(w - 1)
+    if (a === 'center') return ':' + '-'.repeat(w - 2) + ':'
+    if (a === 'right') return '-'.repeat(w - 1) + ':'
+    return '-'.repeat(w)
+  }).join(' | ') + ' |\n'
+
+  // Build body rows
+  for (const row of bodyRows) {
+    const cellContents = getCells(row).map((cell, i) => getCellContent(cell, state).padEnd(colWidths[i] || 0))
+    while (cellContents.length < colWidths.length) cellContents.push(''.padEnd(colWidths[cellContents.length]!))
+    result += '| ' + cellContents.join(' | ') + ' |\n'
+  }
+
+  return result + '\n'
+}
+
+// --- Highlight ranges ---
+
+function formatHighlights(highlights: number[]): string {
+  if (highlights.length === 0) return ''
+  const sorted = [...highlights].sort((a, b) => a - b)
+  const ranges: string[] = []
+  let start = sorted[0]!
+  let end = sorted[0]!
+  for (let i = 1; i <= sorted.length; i++) {
+    if (i < sorted.length && sorted[i] === end + 1) {
+      end = sorted[i]!
+    } else {
+      ranges.push(start === end ? String(start) : `${start}-${end}`)
+      if (i < sorted.length) {
+        start = sorted[i]!
+        end = sorted[i]!
+      }
+    }
+  }
+  return ranges.join(',')
+}
+
+// --- Entry point ---
+
+export function stringifyMinimark(body: { value: MinimarkNode[] }): string {
+  const state = createState()
+  const lastIndex = body.value.length - 1
+
+  return body.value.map((child, index) => {
+    // Strip trailing style elements
+    if (index === lastIndex && Array.isArray(child) && child[0] === 'style') return ''
+    return stringify(child, state)
+  }).join('').trim() + '\n'
+}

package/server/utils/transformMDC.ts

@@ -2,7 +2,7 @@ import type { H3Event } from 'h3'
 import { camelCase, kebabCase, upperFirst } from 'scule'
 import { visit } from '@nuxt/content/runtime'
 // @ts-expect-error - no types available
-import components from '#component-example/nitro'
+import { getComponentExample } from '#component-example/nitro'
 
 type Document = {
   title: string
@@ -179,13 +179,22 @@ export async function transformMDC(event: H3Event, doc: Document): Promise<Docum
   }
 
   // Transform component-example to code block
+  const exampleNodes: any[][] = []
   visitAndReplace(doc, 'component-example', (node) => {
-    const camelName = camelCase(node[1]['name'])
-    const name = camelName.charAt(0).toUpperCase() + camelName.slice(1)
-    const code = components[name].code
-    replaceNodeWithPre(node, 'vue', code, `${name}.vue`)
+    exampleNodes.push(node)
   })
 
+  if (exampleNodes.length) {
+    await Promise.all(exampleNodes.map(async (node) => {
+      const camelName = camelCase(node[1]['name'])
+      const name = camelName.charAt(0).toUpperCase() + camelName.slice(1)
+      const component = await getComponentExample(name)
+      if (component) {
+        replaceNodeWithPre(node, 'vue', component.code, `${name}.vue`)
+      }
+    }))
+  }
+
   // Transform callout components (tip, note, warning, caution, callout) to blockquotes
   const calloutTypes = ['tip', 'note', 'warning', 'caution', 'callout']
   const calloutLabels: Record<string, string> = {

package/utils/meta.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { resolve } from 'pathe'
 import { withHttps } from 'ufo'
 
 export function inferSiteURL() {