Movk Nuxt Docs

Movk Nuxt Docs

配置

View source
学习如何通过 app.config.ts 和 nuxt.config.ts 文件自定义您的 Movk Nuxt Docs 文档，涵盖 SEO、头部、页脚、目录及 GitHub 集成等。

Movk Nuxt Docs 允许您通过 Nuxt 提供的 app.config.ts 文件来配置您的文档。

若要覆盖应用配置，您需要同时创建一个 nuxt.config.ts 文件。否则，您的更改将不会生效。

应用配置

Vercel Analytics

您可以通过在 app.config.ts 文件中启用 Vercel Analytics 来跟踪用户访问数据：

app.config.ts
export default defineAppConfig({
  vercelAnalytics: {
    enable: true, // 启用 Vercel Analytics
    debug: false  // 可选：启用调试模式以查看日志
  },
})

内部支持

SEO

全局配置

在 app.config.ts 文件中为您的整个文档定义默认的 SEO 元数据。

您还可以从 nuxt.config.ts 文件配置 site.name，其默认值基于您 package.json 中的 name 字段。

export default defineAppConfig({
  seo: {
    // 默认为 `%s - ${site.name}`
    titleTemplate: '',
    // 默认为 package.json 的 name 字段
    title: '',
    // 默认为 package.json 的 description 字段
    description: '',
  },
})

按页面配置

content/ 目录中的每个 Markdown 文件都以一个 Front-Matter 块 (---) 开头。您可以通过 seo 键为每个页面单独定义 SEO 元数据：

content/concepts/configuration.md
---
seo:
  title: '配置'
  description: '通过 Nuxt 应用配置文件自定义您的 Movk Nuxt Docs 文档。'
---

<!-- 页面内容 -->
有关 Front-Matter 的更多信息，请参阅 Nuxt Content 指南。

头部 (Header)

app.config.ts
export default defineAppConfig({
  header: {
    title: '', // 标题
    to: '/', // 标题链接
    search: true, // 显示搜索栏
    colorMode: true, // 显示颜色模式切换器
    links: ButtonProps[], // 头部链接按钮
  },
})

页脚 (Footer)

app.config.ts
export default defineAppConfig({
  footer: {
    // 版权信息
    credits: `Copyright © 2024 - ${new Date().getFullYear()} YiXuan - <span class="text-highlighted">MIT License</span>`,
    // 页脚社交媒体图标链接
    socials: [
      {
        icon: 'i-lucide-brain',
        to: 'https://docs.mhaibaraai.cn/llms.txt',
        target: '_blank',
        label: 'Open LLMs',
      },
    ],
  },
})

目录 (TOC)

您可以自定义每个页面右侧的内容目录（Table of Contents）。

app.config.ts
export default defineAppConfig({
  toc: {
    // 自定义目录标题
    title: '本页内容',
    // 在目录底部添加一个区域
    bottom: {
      title: '社区',
      links: [{
        icon: 'i-lucide-book-open',
        label: 'Nuxt UI 文档',
        to: 'https://ui.nuxt.com/getting-started/installation/nuxt',
        target: '_blank',
      }],
    },
  },
})

GitHub 集成

Movk Nuxt Docs 使用 git-url-parse 来获取您仓库的 url 和 branch，以便添加以下功能：

  • 头部和页脚的 GitHub 图标
  • 每个页面页脚的"在 GitHub 上编辑此页"和"报告问题"链接
  • CommitChangelog 组件的提交历史记录获取

基础配置

您可以通过在 app.config.ts 文件中添加以下配置，来自定义文档应用的 GitHub 集成：

app.config.ts
export default defineAppConfig({
  github: {
    branch: 'main',
    rootDir: 'docs',
  },
})

完整配置

对于更高级的需求，您可以设置以下属性：

app.config.ts
export default defineAppConfig({
  github: {
    owner: 'your-username',      // 仓库所有者
    name: 'repo-name',            // 仓库名称
    url: 'https://github.com/...',// 仓库 URL
    branch: 'main',               // 默认分支
    commitPath: 'src',            // 提交历史路径
    suffix: 'vue',                // 文件后缀
    casing: 'auto',               // 文件命名格式（'auto' | 'kebab' | 'camel' | 'pascal'）
    since: '2024-01-01',          // 起始日期（ISO 8601格式）
    until: '2025-12-31',          // 截止日期（可选，ISO 8601格式）
    per_page: 100,                // 每页获取数量（1-100，默认30，建议设为100以提升性能）
    author: 'username',           // 按作者过滤（可选）
    dateFormat: {                 // 日期格式化配置（可选）
      locale: 'zh-CN',
      options: {
        year: 'numeric',
        month: 'numeric',
        day: 'numeric',
        hour: '2-digit',
        minute: '2-digit'
      }
    }
  }
})

配置属性说明：

属性类型默认值描述
ownerstring自动检测仓库所有者用户名
namestring自动检测仓库名称
urlstring自动检测仓库完整 URL
branchstring自动检测Git 分支名称
rootDirstring-文档根目录路径
commitPathstring'src'组件文件所在的基础路径，用于 CommitChangelog 组件
suffixstring'vue'组件文件的默认扩展名，用于 CommitChangelog 组件
casing'auto' | 'kebab' | 'camel' | 'pascal''auto'文件命名格式，用于 CommitChangelog 组件。auto：Vue 文件用 PascalCase，其他用 camelCase；kebab：保持 kebab-case（如 use-user.ts）；camel：camelCase（如 useUser.ts）；pascal：PascalCase（如 UseUser.ts）
sincestring'2025-01-31T04:00:00Z'提交历史的起始时间(ISO 8601 格式)，用于 CommitChangelog 组件
untilstring当前时间提交历史的截止时间(ISO 8601 格式)，用于 CommitChangelog 组件
per_pagenumber100每次请求获取的提交数量 (1-100)，推荐设为 100 以减少 API 调用，用于 CommitChangelog 组件
authorstring-按作者过滤提交记录，可使用 GitHub 用户名或邮箱，用于 CommitChangelog
dateFormatobject{ locale: 'zh-CN', options: {...} }日期格式化配置，用于 PageLastCommit 组件
commitPath、suffix、casing、since、until、per_page 和 author 主要用于 CommitChangelog 组件。dateFormat 用于 PageLastCommit 组件的日期显示格式。了解更多请查看 CommitChangelog 文档。

禁用 GitHub 集成

如果您不希望使用 GitHub 集成，可以将 github 键设置为 false 来禁用它。

app.config.ts
export default defineAppConfig({
  github: false,
})

高级定制

自定义头部链接

通过 composables/useHeader composable，您可以自定义文档应用的头部链接配置，包括桌面端和移动端的导航菜单。

composables/useHeader.ts
export function useHeader() {
  const route = useRoute()

  const desktopLinks = computed(() => [{
    label: '文档',
    to: '/docs/getting-started',
    active: route.path.startsWith('/docs/'),
  }, {
    label: '发布版本',
    to: '/releases',
  }])

  const mobileLinks = computed(() => [{
    label: '快速开始',
    icon: 'i-lucide-square-play',
    to: '/docs/getting-started',
    active: route.path.startsWith('/docs/getting-started'),
  }, {
    label: '基础',
    icon: 'i-lucide-book-open',
    to: '/docs/essentials',
    active: route.path.startsWith('/docs/essentials'),
  }, {
    label: 'Composables',
    icon: 'i-lucide-square-function',
    to: '/docs/composables',
    active: route.path.startsWith('/docs/composables'),
  }, {
    label: '发布版本',
    icon: 'i-lucide-newspaper',
    to: '/releases',
  }, {
    label: 'GitHub',
    to: 'https://github.com/mhaibaraai/movk-nuxt-docs',
    icon: 'i-simple-icons-github',
    target: '_blank',
  }])

  return {
    desktopLinks,
    mobileLinks,
  }
}

自定义页面分类

通过 composables/useCategory composable，您可以为文档页面定义自定义分类和图标，用于在侧边栏中组织和展示内容。

composables/useCategory.ts
export function useCategory() {
  const categories = {
    'getting-started': [
      {
        id: 'core-concepts',
        title: '核心概念',
        icon: 'i-lucide-settings'
      }
    ],
    'components': [
      {
        id: 'components',
        title: 'Components',
        icon: 'i-lucide-layout-dashboard'
      },
      {
        id: 'example',
        title: 'Example',
        icon: 'i-lucide-box'
      }
    ]
  }
  return {
    categories
  }
}

项目结构

深入了解 Movk Nuxt Docs 的项目结构，包括内容组织、配置方式以及如何利用 Nuxt 的完整功能进行扩展。

自定义

了解如何通过覆盖内置组件来自定义您的 Movk Nuxt Docs 文档，包括头部、页脚和页面特定元素，以打造独特的文档外观。

Copyright © 2024 - 2026