@movk/nuxt-docs 1.12.4 → 1.13.1

package/README.md

@@ -41,7 +41,7 @@
 - ⚡ **基于 Nuxt 4** - 充分利用最新的 Nuxt 框架，实现卓越性能
 - 🎨 **采用 Nuxt UI** - 集成全面的 UI 组件库，开箱即用
 - 📝 **MDC 语法增强** - 支持 Markdown 与 Vue 组件的无缝集成
-- 📊 **Mermaid 图表** - 内置 Mermaid 支持，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
+- 📊 **Mermaid 图表** - 可选按需启用，渲染流程图、时序图、类图等可视化图表，支持自动主题切换和全屏查看
 - 🔍 **全文搜索** - 基于 Nuxt Content 的 `ContentSearch` 组件，支持键盘快捷键（⌘K）
 - 🌙 **暗黑模式** - 支持亮色/暗色主题切换
 - 📱 **响应式设计** - 移动优先的响应式布局
@@ -180,7 +180,20 @@ icon: i-lucide-rocket
 
 ### Mermaid 图表
 
-使用 ` ```mermaid ` 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：
+Mermaid 是可选功能，默认不启用。先安装依赖，再开启配置：
+
+```bash
+pnpm add mermaid dompurify
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: ['@movk/nuxt-docs'],
+  mermaid: { enabled: true }
+})
+```
+
+启用后，使用 ` ```mermaid ` 代码块渲染可视化图表，支持流程图、时序图、类图等多种图表类型：
 
 ````md [md]
 ```mermaid
@@ -210,22 +223,7 @@ graph TD
 - **甘特图**（`gantt`）：用于展示项目时间线
 - **饼图**（`pie`）：用于展示数据占比
 - **Git 图**（`gitGraph`）：用于展示分支历史
-- 以及更多 [Mermaid 支持的图表类型](https://mermaid.js.org/intro/)
-
-**带文件名的图表：**
-
-````md [md]
-```mermaid [auth-flow.mmd]
-sequenceDiagram
-    participant U as 用户
-    participant A as 认证服务
-    participant D as 数据库
-    U->>A: 登录请求
-    A->>D: 验证凭证
-    D-->>A: 返回用户信息
-    A-->>U: 返回 Token
-```
-````
+- 以及更多 [Mermaid 支持的图表类型](https://mermaid.js.org/intro())
 
 ## 🛠️ 开发
 

package/app/app.config.ts

@@ -14,11 +14,6 @@ export default defineAppConfig({
     font: 'Public Sans'
   },
   ui: {
-    prose: {
-      codeIcon: {
-        mmd: 'i-vscode-icons-file-type-mermaid'
-      }
-    },
     colors: {
       primary: 'green',
       neutral: 'slate'

package/app/components/content/CommitChangelog.vue

@@ -1,11 +1,27 @@
 <script setup lang="ts">
-import { camelCase, kebabCase, upperFirst } from '@movk/core'
+import { camelCase, kebabCase, upperFirst } from 'scule'
 
 interface Commit {
   sha: string
+  date: string
   message: string
 }
 
+interface Release {
+  tag_name: string
+  published_at: string
+  html_url: string
+}
+
+interface ReleaseGroup {
+  tag: string
+  url?: string
+  icon?: string
+  title: string
+  commits: Commit[]
+  published_at?: string
+}
+
 const props = defineProps<{
   /**
    * 仓库中的文件路径
@@ -45,7 +61,6 @@ const SHA_SHORT_LENGTH = 5
 const { github } = useAppConfig()
 const route = useRoute()
 
-// 计算文件路径相关的值
 const routeName = computed(() => route.path.split('/').pop() ?? '')
 const githubUrl = computed(() => (github && typeof github === 'object' ? github.url : ''))
 
@@ -55,7 +70,6 @@ const filePath = computed(() => {
   const fileExtension = props.suffix ?? (github && typeof github === 'object' ? github.suffix : 'vue')
   const fileName = props.name ?? routeName.value
 
-  // 根据 casing 参数转换文件名
   const transformedName = (() => {
     const casing = props.casing ?? (github && typeof github === 'object' ? github.casing : undefined) ?? 'auto'
 
@@ -82,38 +96,101 @@ const { data: commits } = await useLazyFetch<Commit[]>('/api/github/commits', {
   query: { path: [filePath.value], author: props.author }
 })
 
-// 格式化提交消息
-const formattedCommits = computed(() => {
+const { data: releases } = await useLazyFetch<Release[]>('/api/github/releases.json')
+
+const groupedByRelease = computed<ReleaseGroup[]>(() => {
   if (!commits.value?.length) return []
 
-  return commits.value.map((commit) => {
-    const shortSha = commit.sha.slice(0, SHA_SHORT_LENGTH)
-    const commitLink = `[\`${shortSha}\`](${githubUrl.value}/commit/${commit.sha})`
+  const sortedReleases = (releases.value ?? [])
+    .filter(r => r.published_at)
+    .sort((a, b) => new Date(b.published_at).getTime() - new Date(a.published_at).getTime())
+
+  const releasesOldestFirst = [...sortedReleases].reverse()
+  const groups: ReleaseGroup[] = []
+  const unreleased: Commit[] = []
+
+  for (const commit of commits.value) {
+    const commitDate = new Date(commit.date).getTime()
+    const release = releasesOldestFirst.find(r => new Date(r.published_at).getTime() >= commitDate)
+
+    if (release) {
+      const majorTag = release.tag_name.replace(/-(alpha|beta|rc)\.\d+$/, '')
+      let group = groups.find(g => g.tag === majorTag)
+      if (!group) {
+        group = { tag: majorTag, title: majorTag, icon: 'i-lucide-tag', published_at: release.published_at, url: release.html_url, commits: [] }
+        groups.push(group)
+      }
+      if (new Date(release.published_at) > new Date(group.published_at!)) {
+        group.published_at = release.published_at
+        group.url = release.html_url
+      }
+      group.commits.push(commit)
+    } else {
+      unreleased.push(commit)
+    }
+  }
 
-    const content = commit.message
-      .replace(/\(.*?\)/, '')
-      .replace(/#(\d+)/g, `<a href='${githubUrl.value}/issues/$1'>#$1</a>`)
-      .replace(/`(.*?)`/g, '<code class="text-xs">$1</code>')
+  const result: ReleaseGroup[] = []
+  if (unreleased.length) {
+    result.push({ tag: 'unreleased', title: 'Soon', icon: 'i-lucide-tag', commits: unreleased })
+  }
 
-    return {
-      sha: commit.sha,
-      formatted: `${commitLink} — ${content}`
-    }
-  })
+  const uniqueTags = [...new Set(sortedReleases.map(r => r.tag_name.replace(/-(alpha|beta|rc)\.\d+$/, '')))]
+  groups.sort((a, b) => uniqueTags.indexOf(a.tag) - uniqueTags.indexOf(b.tag))
+  result.push(...groups)
+
+  return result
 })
+
+function normalizeCommitMessage(commit: Commit) {
+  const prefix = `[\`${commit.sha.slice(0, SHA_SHORT_LENGTH)}\`](${githubUrl.value}/commit/${commit.sha})`
+  const content = commit.message
+    .replace(/#(\d+)/g, `<a href='${githubUrl.value}/issues/$1'>#$1</a>`)
+    .replace(/`(.*?)`/g, '<code class="text-xs">$1</code>')
+
+  return `${prefix} — ${content}`
+}
 </script>
 
 <template>
-  <div v-if="!formattedCommits.length">
+  <div v-if="!commits?.length">
     No recent changes
   </div>
 
-  <div v-else class="flex flex-col gap-1.5 relative">
-    <div class="bg-accented w-px h-full absolute left-[11px] z-[-1]" />
-
-    <div v-for="commit of formattedCommits" :key="commit.sha" class="flex gap-1.5 items-center">
-      <div class="bg-accented ring-2 ring-bg size-1.5 mx-[8.5px] rounded-full" />
-      <MDC :value="commit.formatted" class="text-sm *:py-0 *:my-0 [&_code]:text-xs" tag="div" />
-    </div>
-  </div>
+  <UTimeline
+    v-else
+    :items="groupedByRelease"
+    size="xs"
+    :ui="{ root: '', wrapper: 'mt-0 pb-0', title: 'mb-1.5 flex items-center justify-between' }"
+  >
+    <template #title="{ item }">
+      <UBadge
+        v-if="item.tag === 'unreleased'"
+        color="neutral"
+        variant="subtle"
+        :label="item.title"
+        class="w-12.5 justify-center"
+      />
+      <NuxtLink
+        v-else
+        :to="item.url"
+        target="_blank"
+        class="hover:underline"
+      >
+        <UBadge variant="subtle" :label="item.tag" />
+      </NuxtLink>
+
+      <time v-if="item.published_at" :datetime="item.published_at" class="text-xs text-dimmed font-normal">
+        {{ useTimeAgo(new Date(item.published_at)) }}
+      </time>
+    </template>
+
+    <template #description="{ item }">
+      <ul class="flex flex-col gap-1.5">
+        <li v-for="commit of item.commits" :key="commit.sha">
+          <MDC :value="normalizeCommitMessage(commit)" class="text-sm [&_code]:text-xs" unwrap="p" />
+        </li>
+      </ul>
+    </template>
+  </UTimeline>
 </template>

package/app/components/content/prose/ProsePre.global.vue

@@ -2,16 +2,23 @@
 import type { ProsePreProps } from '@nuxt/ui'
 // @ts-ignore
 import NuxtUIProsePre from '@nuxt/ui/components/prose/Pre.vue'
-import Mermaid from '../Mermaid.vue'
 
 const props = defineProps<ProsePreProps>()
 
 const isMermaid = computed(() => props.language === 'mermaid')
+
+// 动态解析 Mermaid 组件（仅在 mermaid 模块启用时可用）
+const MermaidComponent = computed(() => {
+  if (!isMermaid.value) return null
+  const resolved = resolveComponent('Mermaid')
+  return typeof resolved === 'string' ? null : resolved
+})
 </script>
 
 <template>
-  <Mermaid
-    v-if="isMermaid"
+  <component
+    :is="MermaidComponent"
+    v-if="isMermaid && MermaidComponent"
     :code="props.code || ''"
     :filename="props.filename"
     :icon="props.icon"

package/modules/mermaid.ts

@@ -0,0 +1,93 @@
+import { createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+
+export interface MermaidModuleOptions {
+  /**
+   * 是否启用 Mermaid 图表支持
+   *
+   * 启用前需安装依赖: `pnpm add mermaid dompurify`
+   * @default false
+   */
+  enabled?: boolean
+}
+
+const log = logger.withTag('movk-nuxt-docs')
+
+export default defineNuxtModule<MermaidModuleOptions>({
+  meta: {
+    name: 'mermaid',
+    configKey: 'mermaid'
+  },
+  defaults: {
+    enabled: false
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    const mermaidFilePath = resolve('../app/components/content/Mermaid.vue')
+
+    // Layer 自动扫描会注册 Mermaid.vue，通过 components:extend 统一管理：
+    // - 禁用时：从列表移除，resolveComponent('Mermaid') 返回字符串，ProsePre fallback 到普通代码块
+    // - 启用时：将 mode 改为 'client'，避免 SSR 阶段执行
+    nuxt.hooks.hook('components:extend', (components) => {
+      const idx = components.findIndex(c => c.filePath === mermaidFilePath)
+      if (idx === -1) return
+
+      if (!options.enabled) {
+        components.splice(idx, 1)
+        return
+      }
+
+      components[idx]!.mode = 'client'
+    })
+
+    if (!options.enabled) return
+
+    // 验证 mermaid 依赖是否已安装
+    try {
+      import.meta.resolve('mermaid')
+    } catch {
+      log.warn('[mermaid] `mermaid` package not found. Install it with: pnpm add mermaid dompurify')
+      return
+    }
+
+    // 添加 mermaid 语言高亮
+    const contentOptions = nuxt.options.content as Record<string, any> | false
+    if (contentOptions) {
+      const build = contentOptions.build ??= {}
+      const markdown = build.markdown ??= {}
+      const highlight = markdown.highlight ??= {}
+      const langs = highlight.langs ??= [] as string[]
+      if (!langs.includes('mermaid')) {
+        langs.push('mermaid')
+      }
+    }
+
+    // 为 mermaid ESM 兼容性配置 optimizeDeps
+    nuxt.hooks.hook('vite:extendConfig', (config) => {
+      const cfg = config as { optimizeDeps?: { include?: string[] } }
+      cfg.optimizeDeps ??= {}
+      cfg.optimizeDeps.include ??= []
+      cfg.optimizeDeps.include.push(
+        '@movk/nuxt-docs > mermaid',
+        '@movk/nuxt-docs > mermaid > dayjs',
+        '@movk/nuxt-docs > mermaid > @braintree/sanitize-url',
+        '@movk/nuxt-docs > mermaid > d3',
+        '@movk/nuxt-docs > mermaid > dompurify'
+      )
+    })
+
+    // 注入 mermaid 代码图标配置到 appConfig
+    const appConfig = nuxt.options.appConfig as Record<string, any>
+    appConfig.ui ??= {}
+    appConfig.ui.prose ??= {}
+    appConfig.ui.prose.codeIcon ??= {}
+    appConfig.ui.prose.codeIcon.mmd ??= 'i-vscode-icons-file-type-mermaid'
+
+    log.info('[mermaid] Mermaid diagram support enabled')
+  }
+})
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig {
+    mermaid?: MermaidModuleOptions
+  }
+}

package/nuxt.config.ts

@@ -27,7 +27,7 @@ export default defineNuxtConfig({
     build: {
       markdown: {
         highlight: {
-          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml', 'mermaid']
+          langs: ['bash', 'diff', 'json', 'js', 'ts', 'html', 'css', 'vue', 'shell', 'mdc', 'md', 'yaml']
         },
         remarkPlugins: {
           'remark-mdc': {
@@ -100,13 +100,7 @@ export default defineNuxtConfig({
 
       include.push(
         '@movk/nuxt-docs > @nuxt/content > slugify',
-        '@movk/nuxt-docs > @ai-sdk/gateway > @vercel/oidc',
-        // Fix mermaid ESM compatibility issues
-        '@movk/nuxt-docs > mermaid',
-        '@movk/nuxt-docs > mermaid > dayjs',
-        '@movk/nuxt-docs > mermaid > @braintree/sanitize-url',
-        '@movk/nuxt-docs > mermaid > d3',
-        '@movk/nuxt-docs > mermaid > dompurify'
+        '@movk/nuxt-docs > @ai-sdk/gateway > @vercel/oidc'
       )
     }
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.12.4",
+  "version": "1.13.1",
   "private": false,
   "description": "Modern Nuxt 4 documentation theme with auto-generated component docs, AI chat assistant, MCP server, and complete developer experience optimization.",
   "author": "YiXuan <mhaibaraai@gmail.com>",
@@ -14,9 +14,19 @@
   "main": "./nuxt.config.ts",
   "peerDependencies": {
     "better-sqlite3": "12.x",
+    "dompurify": "3.x",
+    "mermaid": "11.x",
     "nuxt": "4.x",
     "tailwindcss": "4.x"
   },
+  "peerDependenciesMeta": {
+    "dompurify": {
+      "optional": true
+    },
+    "mermaid": {
+      "optional": true
+    }
+  },
   "files": [
     "app",
     "content.config.ts",
@@ -56,10 +66,8 @@
     "@vueuse/nuxt": "^14.2.1",
     "ai": "^6.0.99",
     "defu": "^6.1.4",
-    "dompurify": "^3.3.1",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "mermaid": "^11.12.3",
     "minimark": "^1.0.0",
     "motion-v": "^2.0.0",
     "nuxt": "^4.3.1",

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 { data: releases } = await octokit.rest.repos.listReleases({
+    owner: github.owner,
+    repo: github.name
+  })
+
+  return releases
+}, {
+  maxAge: 60 * 60,
+  getKey: () => 'releases'
+})