> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/concepts/customization.md](/docs/manual/zh/concepts/customization.md).

---
title: 自定义
description: 学习如何覆盖 TockDocs 中的内置组件以自定义您的文档。
navigation:
  icon: i-lucide-pen-tool
---

TockDocs 基于 Nuxt 4 构建，提供灵活的组件层系统，允许您通过在自有应用中重新定义特定组件来覆盖 UI 的部分区域。这使得在不触及核心主题的情况下，轻松自定义文档的视觉外观和行为成为可能。

要覆盖组件，只需在 `components/` 目录中创建一个同名的 Vue 文件。TockDocs 将自动使用您的版本而非默认版本。

## 应用页头

您可以通过覆盖以下组件来自定义页头的不同部分：

### `AppHeaderLogo`

对于简单的调整（如更改 logo 大小），您可以使用 `app.config.ts` 中的 `logo.class` 选项而无需覆盖组件（例如 `class: 'h-8'`）。

要完全替换页头中的默认 logo，请创建 `components/AppHeaderLogo.vue` 文件。您的组件将替换 TockDocs 主题提供的默认组件。您可以使用 `useLogoAssets()` 组合式函数来保留带复制和下载操作的右键上下文菜单。

![应用页头 logo 可视化](/documentation/app-header-logo.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppHeaderLogo.vue" variant="link"}
默认组件代码
::

### `AppHeaderLeft`

Logo 位于默认的首页链接包装器中。如果您想更改该链接（URL、属性）或 `AppHeaderLogo` 周围的布局，请覆盖 `components/AppHeaderLeft.vue`。

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppHeaderLeft.vue" variant="link"}
默认组件代码
::

### `AppHeaderCTA`

要自定义页头中的行动号召区域（例如添加「开始使用」按钮或外部链接），请覆盖 `components/AppHeaderCTA.vue` 组件。

![应用页头 CTA 可视化](/documentation/app-header-cta.webp)

::note{to="https://github.com/taowang1993/tockdocs/blob/main/docs/app/components/AppHeaderCTA.vue"}
默认情况下，此组件为空，但您可以查看我们在 TockDocs 文档本身中是如何覆盖它的。
::

### `AppHeaderCenter`

要自定义页头的中间区域，请覆盖 `components/AppHeaderCenter.vue` 组件。您的组件将替换 TockDocs 主题提供的搜索栏。

![应用页头中间区域可视化](/documentation/app-header-center.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppHeaderCenter.vue" variant="link"}
默认组件代码
::

### `AppHeaderBody`

默认情况下，在移动端打开菜单时，TockDocs 会使用 [ContentNavigation](https://ui.nuxt.com/components/content-navigation) 组件将您的 `content/` 目录树显示为菜单。您可以使用 `components/AppHeaderBody.vue` 组件覆盖此菜单，并在移动端填充菜单内容（页头下方）。

![应用页头菜单可视化](/documentation/app-header-body.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppHeaderBody.vue" variant="link"}
默认组件代码
::

### `AppHeaderBottomRight`

当 [`navigation.sub`](/docs/manual/zh/concepts/configuration#sub-navigation) 设置为 `'header'` 时，TockDocs 会在页头下方渲染辅助标签栏。要在此栏右侧添加自定义内容（如开关、徽章），请创建 `components/AppHeaderBottomRight.vue` 组件。

::note{to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppHeaderBottom.vue"}
要完全替换子导航栏，请覆盖 `AppHeaderBottom.vue` 组件。
::

::tip{to="/docs/manual/zh/concepts/nuxt"}
如果您想全局自定义页头，也许应该考虑使用自己的布局。
::

## 应用页脚

您可以通过覆盖以下组件来自定义页脚的不同部分：

### `AppFooterLeft`

要替换页脚的左侧，请创建 `components/AppFooterLeft.vue` 文件。您的组件将替换 TockDocs 主题提供的默认组件。

![应用页脚左侧可视化](/documentation/app-footer-left.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppFooterLeft.vue" variant="link"}
默认组件代码
::

### `AppFooterRight`

要替换页脚的右侧，请创建 `components/AppFooterRight.vue` 文件。您的组件将替换 TockDocs 主题提供的默认组件。

![应用页脚右侧可视化](/documentation/app-footer-right.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/blob/main/layer/app/components/app/AppFooterRight.vue" variant="link"}
默认组件代码
::

::tip{to="/docs/manual/zh/concepts/nuxt"}
如果您想全局自定义页脚，也许应该考虑使用自己的布局。
::

## 文档页面

您还可以自定义文档页面的页头和两侧边栏。

### `DocsPageHeaderLinks`

在文档页面的右侧页头区域，TockDocs 的默认行为是显示一个下拉菜单，其中包含与当前页面 Markdown 源相关的快速操作。它允许文档读者：

- **复制直接链接**到原始 `.md` 文件到剪贴板。
- **在新浏览器标签页中查看 Markdown 源文件**。
- **在 ChatGPT 或 Claude 中打开页面内容**，预填分析 Markdown 文件的提示词。

这些操作对于贡献者、读者或 AI 辅助工作流特别有用，但您可以创建自己的 `components/DocsPageHeaderLinks.vue` 组件来覆盖它。

![应用页头页面链接](/documentation/app-page-header-links.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/tree/main/layer/app/components/docs/DocsPageHeaderLinks.vue" variant="link"}
默认组件代码
::

### `DocsAsideRight`

要完全替换文档页面的右侧边栏，请创建 `components/DocsAsideRight.vue` 组件。

![文档右侧边栏](/documentation/docs-aside-right.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/tree/main/layer/app/components/docs/DocsAsideRight.vue" variant="link"}
默认组件代码
::

### `DocsAsideRightBottom`

要自定义文档页面右侧边栏的底部部分，请创建 `components/DocsAsideRightBottom.vue` 组件。您的组件将替换 TockDocs 主题提供的默认底部目录。

![文档右侧边栏底部](/documentation/docs-aside-right-bottom.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/tree/main/layer/app/components/docs/DocsAsideRightBottom.vue" variant="link"}
默认组件代码
::

### `DocsAsideLeftTop`

要自定义文档页面左侧边栏的顶部部分，请创建 `components/DocsAsideLeftTop.vue` 组件。

![文档左侧边栏顶部](/documentation/docs-aside-left-top.webp)

::note{to="https://github.com/nuxt/image/blob/main/docs/app/components/DocsAsideLeftTop.vue"}
默认情况下，此组件为空，但您可以查看 Nuxt Image 文档本身是如何覆盖它的。
::

### `DocsAsideLeftBody`

要自定义文档页面左侧边栏的主要部分，请创建 `components/DocsAsideLeftBody.vue` 组件。您的组件将替换 TockDocs 主题提供的默认文件导航。

![文档左侧边栏主体可视化](https://ptg90phsi6rf8j7h.public.blob.vercel-storage.com/documentation/docs-aside-left-body.webp)

::u-button{color="neutral" icon="i-lucide-code-xml" to="https://github.com/taowang1993/tockdocs/tree/main/layer/app/components/docs/DocsAsideLeftBody.vue" variant="link"}
默认组件代码
::

## 自定义图标

TockDocs 使用 [Nuxt Icon](https://github.com/nuxt/icon) 搭配 [Iconify](https://iconify.design/) 提供商，让您开箱即用数以千计的图标（例如 `i-lucide-arrow-right`、`i-simple-icons-github`）。

要添加您自己的图标，请将 SVG 文件放入应用的 `assets/icons/` 目录中。它们将自动以 `custom` 前缀注册，并可在项目的任何地方使用。

```
assets/
  icons/
    my-logo.svg
```

然后您可以使用 `i-custom:` 前缀来使用它们：

```md [content/getting-started.md]
---
navigation:
  icon: i-custom:my-logo
---
```

```ts [app.config.ts]
export default defineAppConfig({
  toc: {
    bottom: {
      links: [
        {
          icon: 'i-custom:my-logo',
          label: '预览',
          to: '/preview',
        },
      ],
    },
  },
})
```

```vue [components/MyComponent.vue]
<template>
  <UIcon name="i-custom:my-logo" />
</template>
```

::tip{to="https://iconify.design/docs/icons/icon-set-basics.html"}
SVG 文件应使用 `currentColor` 进行填充和描边，以便图标能自适应文本颜色。
::