如何有效地链接文档页面

链接将你的文档连接成一个连贯的系统。它们帮助用户发现相关内容、高效导航，并沿着逻辑路径浏览复杂主题。糟糕的链接——模糊的锚文本、缺失的交叉引用、损坏的 URL——会使文档更难使用并损害 SEO。

本指南介绍如何在 Mintlify 中创建不同类型的链接，以及如何随着文档的增长维护链接完整性。

使用根相对路径链接到文档中的其他页面。根相对路径从文档目录的根目录开始，无论链接页面在目录结构中的位置如何，都能一致地工作。

- [Quickstart guide](/quickstart)
- [API overview](/api-playground/overview)
- [Custom components](/customize/react-components)

Mintlify 根据源文件在项目目录中的位置解析相对路径（./ 和 ../）。这适用于链接、图像以及 <Card> 和 <a> 等 JSX 元素。

- [同级页面](./sibling-page)
- [上级部分页面](../other-page)

对于 index.mdx 文件，相对路径从包含索引文件的目录开始解析。例如，guides/getting-started/index.mdx 中的 ./setup 链接会解析为 /guides/getting-started/setup。

链接会保留片段和查询字符串。

[设置说明](./setup#step-1)

锚点链接指向页面内的特定部分。每个标题会根据其文本自动生成一个锚点。

使用井号引用当前页面上的标题：

[Jump to best practices](#best-practices)

将页面路径与锚点组合：

- [Customize your playground](/api-playground/overview#customize-your-playground)
- [Cards properties](/components/cards#properties)

Mintlify 通过将标题文本转换为小写、用连字符替换空格并删除特殊字符来自动创建锚点。

通过在标题文本后附加 {#custom-id} 来覆盖任何标题的自动生成锚点：

## Configuration options [#config]

此标题可通过 #config 访问，而不是 #configuration-options。自定义 ID 在你更新标题文本时保持锚点链接稳定——这对你经常链接到的标题很有用。详情请参阅格式化文本。

深层链接指向页面内的特定状态或位置，而不仅仅是页面本身。

当用户打开手风琴时，URL 哈希会更新以反映打开状态。访问带有该哈希的 URL 会自动打开并滚动到该手风琴。

默认情况下，哈希源自手风琴的 title。使用 id 属性设置自定义哈希：

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

此手风琴可通过 #install 访问，而不是自动生成的 #installation-steps。详情请参阅手风琴。

要在链接中打开 API playground，请将 ?playground=open 附加到任何端点页面 URL：

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

当用户打开或关闭 playground 时，URL 会更新。在支持对话或入门流程中使用 playground 深层链接，将用户直接发送到端点的交互式 playground。详情请参阅 API playground 了解参数锚点链接信息。

链接到外部资源时，编写能清楚说明目标的锚文本：

See the [OpenAPI specification](https://swagger.io/specification/) in the Swagger documentation for details.

锚文本应在用户点击前告知他们要去往何处。模糊的短语如”点击这里”或”阅读更多”也是比描述性文本更弱的 SEO 信号。

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

当页面假设已完成先前步骤时，在顶部链接到这些步骤，而不是假设用户会自己找到它们：

## Prerequisites

Before deploying your documentation, ensure you have:

- Completed the [quickstart guide](/quickstart)
- Configured your [custom domain](/customize/custom-domain)
- Set up [authentication](/deploy/authentication-setup) if needed

将相关内容链接在一起，帮助用户——和搜索引擎——理解你如何组织文档：

## Related topics

- [API authentication](/api-playground/overview#authentication)
- [Adding SDK examples](/api-playground/adding-sdk-examples)
- [Managing page visibility](/api-playground/managing-page-visibility)

在发布前运行 Mintlify CLI 以捕获损坏的内部和外部链接：

mint broken-links

移动或重命名页面时：

1. 在导航配置中更新页面路径。
2. 配置从旧路径到新路径的重定向。
3. 在文档中搜索对旧路径的引用。
4. 更新所有内部链接以使用新路径。
5. 运行 mint broken-links 进行验证。

永久移动内容时，添加重定向以防止已收藏或分享旧 URL 的用户遇到断链。

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

详情请参阅重定向。

• 格式化文本：Markdown 格式选项，包括标题 ID 和锚点行为。
• 导航：配置文档结构。
• 重定向：为已移动的内容设置重定向。