配置

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

SEO

技术 SEO 既棘手又繁琐。TockDocs 提供了一套可靠、可选用的默认设置，开箱即用，同时让您完全控制自定义 SEO 元数据，从页面标题到社交分享图片。

元数据

TockDocs 提供灵活的 SEO 元数据配置，允许您轻松地在全局或每页基础上覆盖值。

全局配置

在 app.config.ts 中为整个文档定义默认的 SEO 元数据。这些值将作为未在 frontmatter 中指定自己值的页面的回退值。

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

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

export default defineNuxtConfig({
  site: {
    name: 'TockDocs',
  },
})

每页配置

content/ 目录中的每个 Markdown 文件以 frontmatter 块（---）开头。您可以使用 seo 键为每页定义 SEO 元数据：

---
seo:
  title: '配置'
  description: '通过 Nuxt 应用配置文件自定义您的 TockDocs 文档。'
---

<!-- 页面内容 -->

社交分享（OG）图片

当您在社交媒体或某些聊天平台上分享文档链接时，链接将被 展开，即显示某人链接内容的预览（显示标题、描述和图片）。所有这些都由 Open Graph 协议 提供支持。

文档页面

我们底层使用 Nuxt OG Image 为每个文档页面生成 OG 图片，基于提供的标题和描述。

首页

与文档页面相同，首页使用相同的 OG 图片生成器，基于提供的标题和描述。确切路由取决于页面元数据编码后的结果，因此请使用构建产物中生成的路径，或直接检查渲染后的页面源码。

/_og/s/c_Landing,title_Your+Site,description_Your+landing+page+description.png

覆盖 OG 图片

由于 TockDocs 是一个 Nuxt 层，您可以通过在自己的 components/OgImage/ 目录中创建同名文件来覆盖文档或首页的 OG 图片。

components/
  OgImage/
    Docs.takumi.vue     # 覆盖文档 OG 图片
    Landing.takumi.vue  # 覆盖首页 OG 图片

您的组件接收 title、description 和 headline（仅文档）作为属性，并可以使用 Takumi 渲染器 支持的任何 Tailwind CSS 或内联样式。

站点地图

TockDocs 自动在 /sitemap.xml 生成包含所有文档页面的站点地图。这有助于搜索引擎发现和索引您的内容。

排除页面

要从站点地图中排除特定页面，请在其 frontmatter 中添加 sitemap: false：

---
sitemap: false
---

此页面不会出现在站点地图中。

站点 URL

为了生成正确的站点地图 URL，请设置 NUXT_SITE_URL 环境变量：

NUXT_SITE_URL=https://your-site.com

页头

配置您文档站点的 title 或 logo：

export default defineAppConfig({
  header: {
    title: '',
    logo: {
      light: '',
      dark: '',
      alt: '',
    },
  },
})

品牌资源

您可以为 logo 配置额外的品牌资源。右键单击页头中的 logo 会打开一个包含复制和下载操作的上下文菜单。

export default defineAppConfig({
  header: {
    title: 'My Project',
    logo: {
      light: '/logo/logo-dark.svg',
      dark: '/logo/logo-light.svg',
      alt: 'My Project Logo',
      favicon: '/favicon.svg',
      brandAssetsUrl: 'https://example.com/brand',
    },
  },
})

当 logo 是 SVG 格式时，上下文菜单提供复制 logo 和下载 logo 操作，可复制带有 currentColor 描边和填充的原始 SVG，随时可粘贴到 Figma 或任何设计工具中。对于非 SVG 格式（PNG 等），仅提供下载操作。

如果您使用 SVG favicon，可以在 SVG 内部使用 prefers-color-scheme 媒体查询使其感知主题。

颜色模式

默认情况下，TockDocs 在页头和页脚中包含颜色模式切换，允许用户在浅色和深色模式之间切换。

如果您的文档只使用一种主题，您可以通过设置 colorMode 选项来强制指定：

export default defineAppConfig({
  tockdocs: {
    colorMode: 'dark',
  },
})

当强制使用某种颜色模式时，切换按钮会在页头和页脚中隐藏，并且命令面板中的颜色模式命令也会被移除。

导航

子导航

对于有许多内容分区的文档站点，您可以启用子导航，将顶级内容文件夹拆分为分区，并过滤左侧边栏仅显示活动分区的页面。

提供两种显示模式：

• header — 在页头下方渲染辅助标签栏（仅桌面端，移动端使用抽屉）
• aside — 在左侧边栏顶部渲染分区锚点（移动端使用抽屉）

export default defineAppConfig({
  navigation: {
    sub: 'header', // 或 'aside'
  },
})

社交链接

在页脚中使用 Record<string, string> 添加您的社交媒体链接，键名与 Simple Icons 库中的图标匹配。

export default defineAppConfig({
  socials: {
    x: 'https://x.com/nuxt_js',
    discord: 'https://discord.com/invite/ps2h6QT',
    nuxt: 'https://nuxt.com',
  },
})

目录

您可以自定义每个页面右侧边栏的目录。

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',
        },
      ],
    },
  },
})

语言设置

对于单语言文档（不使用完整的 @nuxtjs/i18n 模块），您可以通过 app.config.ts 配置语言：

export default defineAppConfig({
  tockdocs: {
    locale: 'zh', // 默认: 'en'
  },
})

GitHub 集成

TockDocs 读取您的 .git/ 文件夹以获取仓库的 url 和 branch，并添加：

• 页头和页脚中的 GitHub 图标
• 每个页面页脚中的「编辑此页」和「报告问题」链接。

export default defineAppConfig({
  github: {
    url: 'https://github.com/taowang1993/tockdocs',
    branch: 'main',
    rootDir: 'docs',
  },
})

如果您不想使用 GitHub，可以将 github 键设为 false 以禁用 GitHub 集成。

export default defineAppConfig({
  github: false,
})