链接

了解如何创建内部链接、引用 API 端点，并在整个文档中维护链接完整性。

有效的链接可以构建起连贯一致的文档体验，帮助用户发现相关内容并高效地浏览与导航。过多的链接或失效链接会让用户感到困惑，削弱文档的效果。本指南将介绍如何在整个文档中创建和维护链接。

​

内部链接

使用根相对路径来链接到文档中的其他页面。根相对路径从文档目录的根目录开始，不受当前链接页面位置影响，因而始终能一致地生效。

* [快速入门指南](/quickstart)
* [API 概述](/api-playground/overview)
* [自定义组件](/customize/react-components)

• 快速入门指南
• API 概览
• 自定义组件

​

锚点链接

锚点链接让你可以直接链接到页面中的特定部分。每个标题都会根据其文本自动生成一个锚点链接。

​

链接到同一页面中的标题

使用 hash 符号来引用本页的标题：

[跳转至最佳实践](#best-practices)

前往最佳实践

​

链接到其他页面中的标题

将页面路径与锚点链接拼接使用。

* [自定义你的 API 演练场](/api-playground/overview#customize-your-playground)
* [Cards properties](/components/cards#properties)

• 自定义你的 Playground
• Cards 属性

​

锚点链接是如何生成的

锚点链接会根据标题文本自动创建。

• 转换为小写形式
• 将空格替换为连字符
• 移除特殊字符
• 保留数字和字母

标题文本	锚点链接
## Getting Started	#getting-started
### API Authentication	#api-authentication
#### Step 1: Install	#step-1-install

带有 noAnchor prop 的标题不会生成锚点链接。详情请参阅 Format text。

​

深度链接

深度链接指向页面内的特定状态或位置，而不仅仅是页面本身。使用深度链接可以将用户直接导向已展开的手风琴组件或 API playground 视图。

​

手风琴深度链接

当用户展开手风琴时，URL 的 hash 会更新以反映展开状态。访问带有该 hash 的 URL 时，手风琴会自动展开并滚动到相应位置。

默认情况下，hash 由手风琴的 title 派生。使用 id 属性设置自定义 hash：

<Accordion title="Installation steps" id="install">
  ...
</Accordion>

此手风琴可通过 #install 访问，而非自动生成的 #installation-steps。

详情请参阅手风琴。

​

API playground 深度链接

要通过链接打开 API playground，请在任意端点页面的 URL 后追加 ?playground=open：

https://your-docs-url/endpoint-path?playground=open

当用户打开或关闭 playground 时，URL 会随之更新。使用 playground 深度链接可以在支持对话或引导流程中分享直达某个端点交互式 playground 的链接。

详情请参阅 API playground 了解参数锚点链接。

​

链接到 API 端点

在编写 API 文档时，你可以在文档中的任何位置链接到特定端点。

通过它们在导航中的路径链接到对应的 API 端点页面。

​

链接到外部页面

在链接到外部资源时，应让用户清楚地知道该链接会跳转到文档之外的页面。

了解更多关于 [Markdown 语法](https://www.markdownguide.org/)的信息(外部链接)。

有关详细信息,请参阅 Swagger 文档中的 [OpenAPI 规范](https://swagger.io/specification/)。

​

最佳实践

​

编写描述性链接文本

使用清晰、具体的文本，让用户一眼就知道链接会把他们带到哪里。

Good examples

See [Hidden pages](/organize/hidden-pages) for more information.
[Configure custom domains](/customize/custom-domain)

​

创建主题集群

将相关内容相互链接起来，帮助用户发现相关信息。

## 相关主题

- [API 认证](/api-playground/overview#authentication)
- [添加 SDK 示例](/api-playground/adding-sdk-examples)
- [管理页面可见性](/api-playground/managing-page-visibility)

​

使用上下文链接

在内容中自然地添加链接，只在它们真正能提供价值的地方使用。

要自定义文档外观,请在设置中配置[主题](/customize/themes)和[字体](/customize/fonts)。您还可以添加[自定义脚本](/customize/custom-scripts)以实现高级特性。

​

链接到先决条件

通过链接到先决条件相关内容来帮助用户做好准备：

## 前置条件

在部署文档之前,请确保您已:

- 完成[快速入门指南](/quickstart)
- 配置[自定义域名](/customize/custom-domain)
- 如有需要,设置[认证](/deploy/authentication-setup)

​

避免循环链接

不要创建会让用户在同一组页面之间反复来回跳转的链接。

​

检查失效链接

使用 Mintlify 命令行界面 (CLI) 检测文档中的失效链接。

mint broken-links

​

在重新组织文档时更新链接

在移动或重命名页面时：

1. 在 navigation 配置中更新页面路径。
2. 为旧路径配置重定向到新路径。
3. 在文档中搜索所有对旧路径的引用。
4. 将所有内部链接更新为使用新路径。
5. 运行 mint broken-links 检查所有链接是否正常工作。

​

为已移动的内容设置重定向

在永久移动内容时，请添加重定向，避免出现无效链接。

{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    }
  ]
}

详情请参阅重定向。

​

相关资源

• 格式化文本: 了解如何使用 Markdown 进行格式化。
• 导航: 配置文档结构。
• 重定向: 为已移动的内容设置重定向。