> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/concepts/configuration.md](/docs/manual/zh/concepts/configuration.md). --- title: 配置 description: 通过 Nuxt 应用配置文件自定义您的 TockDocs 文档。 navigation: icon: i-lucide-settings seo: description: 通过 Nuxt 应用配置文件自定义您的 TockDocs 文档。 title: 配置 --- TockDocs 允许您通过 Nuxt 提供的 [app.config.ts](https://nuxt.com/docs/guide/directory-structure/app-config) 文件来配置您的文档。 ::warning 您需要有一个 `nuxt.config.ts` 才能覆盖应用配置。没有现有的 Nuxt 配置文件，更改将不会生效。 :: ## SEO 技术 SEO 既棘手又繁琐。TockDocs 提供了一套可靠、可选用的默认设置，开箱即用，同时让您完全控制自定义 SEO 元数据，从页面标题到社交分享图片。 ### 元数据 TockDocs 提供灵活的 `SEO` 元数据配置，允许您轻松地在全局或每页基础上覆盖值。 #### 全局配置 在 `app.config.ts` 中为整个文档定义默认的 `SEO` 元数据。这些值将作为未在 frontmatter 中指定自己值的页面的回退值。 您还可以从 `nuxt.config.ts` 文件配置 `site.name` 值，默认基于您的 `package.json` 名称。 ::code-group ```ts [app.config.ts] export default defineAppConfig({ seo: { // 默认为 `%s - ${site.name}` titleTemplate: '', // 默认为 package.json 名称 title: '', // 默认为 package.json 描述 description: '', }, }) ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ site: { name: 'TockDocs', }, }) ``` :: #### 每页配置 `content/` 目录中的每个 Markdown 文件以 frontmatter 块（`---`）开头。您可以使用 `seo` 键为每页定义 `SEO` 元数据： ```md [content/concepts/configuration.md] --- seo: title: '配置' description: '通过 Nuxt 应用配置文件自定义您的 TockDocs 文档。' --- ``` ::tip{to="/docs/manual/zh/concepts/edition#frontmatter"} 有关 frontmatter 的更多详细信息，请参阅内容编辑指南。 :: ### 社交分享（OG）图片 当您在社交媒体或某些聊天平台上分享文档链接时，链接将被 **展开**，即显示某人链接内容的预览（显示标题、描述和图片）。所有这些都由 **Open Graph 协议** 提供支持。 #### 文档页面 我们底层使用 [Nuxt OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction) 为每个文档页面生成 OG 图片，基于提供的标题和描述。 :site-image{.rounded-md.w-full alt="OG 图片文档页面" src="/_og/s/c_Docs,headline_Core+Concepts,title_Configuration,description_Customize+your+TockDocs+documentation+from+Nuxt+application+configuration+file.,p_Ii9kb2NzL21hbnVhbC9lbi9jb25jZXB0cy9jb25maWd1cmF0aW9uIg.png"} #### 首页 与文档页面相同，首页使用相同的 OG 图片生成器，基于提供的标题和描述。确切路由取决于页面元数据编码后的结果，因此请使用构建产物中生成的路径，或直接检查渲染后的页面源码。 ```text /_og/s/c_Landing,title_Your+Site,description_Your+landing+page+description.png ``` #### 覆盖 OG 图片 由于 TockDocs 是一个 [Nuxt 层](https://nuxt.com/docs/guide/going-further/layers)，您可以通过在自己的 `components/OgImage/` 目录中创建同名文件来覆盖文档或首页的 OG 图片。 ```text components/ OgImage/ Docs.takumi.vue # 覆盖文档 OG 图片 Landing.takumi.vue # 覆盖首页 OG 图片 ``` 您的组件接收 `title`、`description` 和 `headline`（仅文档）作为属性，并可以使用 [Takumi 渲染器](https://nuxtseo.com/docs/og-image/guides/renderers) 支持的任何 Tailwind CSS 或内联样式。 ### 站点地图 TockDocs 自动在 `/sitemap.xml` 生成包含所有文档页面的站点地图。这有助于搜索引擎发现和索引您的内容。 #### 排除页面 要从站点地图中排除特定页面，请在其 frontmatter 中添加 `sitemap: false`： ```md [content/draft-page.md] --- sitemap: false --- 此页面不会出现在站点地图中。 ``` #### 站点 URL 为了生成正确的站点地图 URL，请设置 `NUXT_SITE_URL` 环境变量： ```bash NUXT_SITE_URL=https://your-site.com ``` ## 页头 配置您文档站点的 `title` 或 `logo`： ```ts [app.config.ts] export default defineAppConfig({ header: { title: '', logo: { light: '', dark: '', alt: '', }, }, }) ``` ### 品牌资源 您可以为 logo 配置额外的品牌资源。右键单击页头中的 logo 会打开一个包含复制和下载操作的上下文菜单。 ```ts [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', favicon: '/favicon.svg', brandAssetsUrl: 'https://example.com/brand', }, }, }) ``` | 字段 | 描述 | | ----------------------- | --------------------------------------------------------------------- | | `logo.class` | 在 logo 图片上的额外 CSS 类（例如 `'h-8'`）。 | | `logo.favicon` | 浏览器标签页和品牌资源下载中使用的 favicon 文件路径。默认为 `/favicon.ico`。 | | `logo.brandAssetsUrl` | 品牌资源页面的链接，显示为菜单项。 | 当 logo 是 SVG 格式时，上下文菜单提供**复制 logo** 和**下载 logo** 操作，可复制带有 `currentColor` 描边和填充的原始 SVG，随时可粘贴到 Figma 或任何设计工具中。对于非 SVG 格式（PNG 等），仅提供下载操作。 如果您使用 SVG favicon，可以在 SVG 内部使用 `prefers-color-scheme` 媒体查询使其感知主题。 ## 颜色模式 默认情况下，TockDocs 在页头和页脚中包含颜色模式切换，允许用户在浅色和深色模式之间切换。 如果您的文档只使用一种主题，您可以通过设置 `colorMode` 选项来强制指定： ```ts [app.config.ts] export default defineAppConfig({ tockdocs: { colorMode: 'dark', }, }) ``` | 值 | 行为 | | ---------------- | ------------------------ | | `''`（默认） | 跟随系统偏好，显示切换按钮 | | `'light'` | 强制浅色模式，隐藏切换 | | `'dark'` | 强制深色模式，隐藏切换 | 当强制使用某种颜色模式时，切换按钮会在页头和页脚中隐藏，并且命令面板中的颜色模式命令也会被移除。 ## 导航 ### 子导航 对于有许多内容分区的文档站点，您可以启用子导航，将顶级内容文件夹拆分为分区，并过滤左侧边栏仅显示活动分区的页面。 提供两种显示模式： - **`header`** — 在页头下方渲染辅助标签栏（仅桌面端，移动端使用抽屉） - **`aside`** — 在左侧边栏顶部渲染分区锚点（移动端使用抽屉） ```ts [app.config.ts] export default defineAppConfig({ navigation: { sub: 'header', // 或 'aside' }, }) ``` :sub-navigation-preview{locale="zh"} ::note 标签页从 `content/` 中的顶级文件夹自动生成。每个文件夹的标题和图标从其 `.navigation.yml` 文件中读取。 :: ## 社交链接 在页脚中使用 `Record` 添加您的社交媒体链接，键名与 [Simple Icons](https://simpleicons.org/) 库中的图标匹配。 ```ts [app.config.ts] export default defineAppConfig({ socials: { x: 'https://x.com/nuxt_js', discord: 'https://discord.com/invite/ps2h6QT', nuxt: 'https://nuxt.com', }, }) ``` ## 目录 您可以自定义每个页面右侧边栏的目录。 ```ts [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', }, ], }, }, }) ``` ## 语言设置 对于单语言文档（不使用完整的 `@nuxtjs/i18n` 模块），您可以通过 `app.config.ts` 配置语言： ```ts [app.config.ts] export default defineAppConfig({ tockdocs: { locale: 'zh', // 默认: 'en' }, }) ``` ::tip{to="/docs/manual/zh/concepts/internationalization"} 有关带语言切换的多语言文档，请参阅[国际化指南](/docs/manual/zh/concepts/internationalization)。 :: ## GitHub 集成 TockDocs 读取您的 `.git/` 文件夹以获取仓库的 `url` 和 `branch`，并添加： - 页头和页脚中的 GitHub 图标 - 每个页面页脚中的「编辑此页」和「报告问题」链接。 ```ts [app.config.ts] export default defineAppConfig({ github: { url: 'https://github.com/taowang1993/tockdocs', branch: 'main', rootDir: 'docs', }, }) ``` 如果您不想使用 GitHub，可以将 `github` 键设为 `false` 以禁用 GitHub 集成。 ```ts [app.config.ts] export default defineAppConfig({ github: false, }) ``` ::tip{to="/docs/manual/zh/getting-started/studio"} 这些配置也可以在 Studio 编辑器中处理，试试看！ ::