Krab logoKrab
核心概念

配置

通过 Nuxt 应用配置文件自定义 Docus 文档。

Docus 允许你通过 Nuxt 提供的 app.config.ts 文件配置文档。

如果想覆盖 app config，需要先设置 nuxt.config.ts。没有 Nuxt 配置文件时，改动不会生效。

SEO

技术 SEO 复杂又容易枯燥。Docus 提供稳定、开箱即用的默认设置，同时让你完全控制 SEO 元数据，从页面标题到社交分享图片都可以自定义。

Metadata

Docus 提供灵活的 SEO 元数据配置，让你可以轻松在全局或单页层面覆盖值。

Global configuration

在 app.config.ts 中为整个文档定义默认 SEO metas。这些值会作为没有在 frontmatter 中指定自身 SEO 的页面的 fallback。

你也可以在 nuxt.config.ts 中配置 site.name，默认值基于 package.json 的名称。

export default defineAppConfig({
  seo: {
    // Default to `%s - ${site.name}`
    titleTemplate: '',
    // Default to package.json name
    title: '',
    // Default to package.json description
    description: ''
  },
})

Per-page configuration

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

content/concepts/configuration.md
---
seo:
  title: 'Configuration'
  description: 'Customize your Docus documentation from the Nuxt application configuration file.'
---

<!-- Page content -->
更多 frontmatter 细节请查看编辑指南。

Social sharing (OG) image

当你在社交媒体或聊天平台分享文档链接时，链接会被展开预览，也就是展示标题、描述和图片。所有这些都由 Open Graph Protocol 驱动。

文档页面

Docus 底层使用 Nuxt OG Image，基于提供的标题和描述为每个文档页面生成 OG 图片。例如，当前页面的 OG 图片是：

着陆页

和文档页面一样，着陆页也会基于提供的标题和描述使用同一个 OG 图片生成器。

Override OG image

Docus 是一个 Nuxt layer，因此你可以在自己的 components/OgImage/ 目录中创建同名文件来覆盖 docs 或 landing page 的 OG 图片。

components/
  OgImage/
    Docs.takumi.vue     # overrides the docs OG image
    Landing.takumi.vue  # overrides the landing OG image

你的组件会接收 title、description 和 headline（仅 docs）作为 props，并可以使用 Takumi renderer 支持的任意 Tailwind CSS 或内联样式。

Sitemap

Docus 会自动在 /sitemap.xml 生成包含所有文档页面的 sitemap，帮助搜索引擎发现并索引内容。

Excluding pages

要从 sitemap 中排除某个页面，请在 frontmatter 中添加 sitemap: false：

content/draft-page.md
---
sitemap: false
---

这个页面不会出现在 sitemap 中。

Site URL

为了生成正确的 sitemap URL，请设置 NUXT_SITE_URL 环境变量：

NUXT_SITE_URL=https://your-site.com

Header

配置文档站点的 title 或 logo：

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

Brand Assets

你可以为 Logo 配置额外品牌资源。右键点击页眉中的 Logo 会打开包含复制和下载操作的上下文菜单。

app.config.ts
export default defineAppConfig({
  header: {
    title: 'My Project',
    logo: {
      light: '/logo/logo-dark.svg',
      dark: '/logo/logo-light.svg',
      alt: 'My Project Logo',
      wordmark: {
        light: '/logo/wordmark-dark.svg',
        dark: '/logo/wordmark-light.svg',
      },
      favicon: '/favicon.svg',
      brandAssetsUrl: 'https://example.com/brand',
    },
  },
})
字段描述
logo.wordmark.light / dark每种颜色模式下的完整字标（图标 + 文本）。
logo.display页眉中显示的变体：'logo'（默认）或 'wordmark'。
logo.classLogo 图片上的额外 CSS classes（例如 'h-8'）。
logo.faviconfavicon 文件路径，默认为 /favicon.ico。
logo.brandAssetsUrl品牌资源页面链接，会显示为菜单项。

当 Logo 是 SVG 时，上下文菜单会提供 Copy logo 和 Copy wordmark 操作，复制带有 currentColor fill 的原始 SVG，可直接粘贴到 Figma 或任何设计工具中。对于非 SVG 格式（PNG 等），只会提供下载操作。

Color Mode

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

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

app.config.ts
export default defineAppConfig({
  docus: {
    colorMode: 'dark'
  }
})
值行为
''（默认）跟随系统偏好，并显示切换按钮
'light'强制浅色模式，隐藏切换按钮
'dark'强制深色模式，隐藏切换按钮

Keyboard Shortcut

当颜色模式切换按钮可见时，按 D 可以在浅色和深色模式之间切换。

你可以在 app.config.ts 中自定义或禁用这个快捷键：

app.config.ts
export default defineAppConfig({
  docus: {
    shortcuts: {
      toggleColorMode: 'd', // Default
    },
  },
})

将 toggleColorMode 设置为空字符串即可禁用快捷键。快捷键格式（meta_d、ctrl_shift_p 等）可查看 Assistant 页面。

强制固定颜色模式时，切换按钮会从页眉和页脚中隐藏，颜色模式命令也会从命令面板中移除。

Navigation

Sub Navigation

对于包含许多内容章节的文档站点，你可以启用子导航。它会把顶级内容文件夹拆分为多个章节，并过滤左侧边栏，只显示当前激活章节的页面。

有两种显示模式：

  • header — 在页眉下方渲染二级标签栏（仅桌面端，移动端使用 drawer）
  • aside — 在左侧边栏顶部渲染章节锚点（移动端使用 drawer）
app.config.ts
export default defineAppConfig({
  navigation: {
    sub: 'header', // or 'aside'
  },
})
这些标签会根据 content/ 中的顶级文件夹自动生成。每个文件夹的标题和图标会从对应 .navigation.yml 文件中读取。

搜索

Docus 内置由 Nuxt UI ContentSearch 驱动的全文搜索。默认情况下，它使用客户端 Fuse.js 过滤，并会预先加载所有搜索 sections。

FTS5 全文搜索

你可以切换到 SQLite FTS5，获得更快的索引搜索和内置片段高亮。它使用 SQLite WASM 在浏览器中构建 FTS5 索引，只在输入查询时运行搜索，而不是预先加载所有 sections。

app.config.ts
export default defineAppConfig({
  search: {
    fts: true
  }
})
模式索引速度拼写容错预加载负载
Fuse.js（默认）内存 JS 扫描每次查询 O(n)完整模糊匹配加载所有 sections
FTS5SQLite 倒排索引O(log n) 查找仅前缀无

Socials Links

使用 Record<string, string> 在页脚添加社交媒体链接，其中 key 对应 Simple Icons 图标库中的图标。

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

Table of Contents

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

app.config.ts
export default defineAppConfig({
  toc: {
    // Rename the title of the table of contents
    title: 'On this page',
    // Add a bottom section to the table of contents
    bottom: {
      title: 'Community',
      links: [{
        icon: 'i-lucide-book-open',
        label: 'Nuxt UI docs',
        to: 'https://ui.nuxt.com/getting-started/installation/nuxt',
        target: '_blank'
      }]
    }
  }
})

Locale

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

app.config.ts
export default defineAppConfig({
  docus: {
    locale: 'zh-cn', // 默认：'en'
  }
})

这会设置以下内容的语言：

  • UI 组件翻译
  • <html> 标签上的 lang 和 dir 属性
  • Docus 内置界面字符串
如果需要带语言切换的多语言文档，请查看国际化指南。

GitHub Integration

Docus 会读取 .git/ 文件夹，获取仓库的 url 和 branch，用于添加：

  • 页眉和页脚中的 GitHub 图标
  • 每个页面页脚中的 Edit this page 和 Report an issue 链接

你可以在 app.config.ts 文件中添加以下配置来自定义文档应用的 url、branch 和 rootDir：

app.config.ts
export default defineAppConfig({
  github: {
    url: 'https://github.com/nuxt-content/docus',
    branch: 'main',
    rootDir: 'docs'
  }
})

如果不想使用 GitHub，可以将 github key 设置为 false 来禁用 GitHub 集成。

app.config.ts
export default defineAppConfig({
  github: false
})
这些配置也可以在 Studio 编辑器中处理，试试看！

编辑

学习如何编写文档。

主题

借助 Nuxt UI 灵活的主题系统自定义 Docus 文档外观。

Copyright © 2026 Powered by Docus