mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
73edda4d1f
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
214 lines
5.8 KiB
Plaintext
214 lines
5.8 KiB
Plaintext
---
|
|
title: "链接"
|
|
description: "了解如何创建内部链接、引用 API 端点，并在整个文档中维护链接完整性。"
|
|
keywords: ["内部链接", "交叉引用", "锚点链接", "失效链接"]
|
|
---
|
|
|
|
有效的链接可以构建起连贯一致的文档体验，帮助用户发现相关内容并高效地浏览与导航。过多的链接或失效链接会让用户感到困惑，削弱文档的效果。本指南将介绍如何在整个文档中创建和维护链接。
|
|
|
|
<div id="internal-links">
|
|
## 内部链接
|
|
</div>
|
|
|
|
使用根相对路径来链接到文档中的其他页面。根相对路径从文档目录的根目录开始，不受当前链接页面位置影响，因而始终能一致地生效。
|
|
|
|
```mdx
|
|
* [快速入门指南](/quickstart)
|
|
* [API 概述](/api-playground/overview)
|
|
* [自定义组件](/customize/react-components)
|
|
```
|
|
|
|
* [快速入门指南](/zh/quickstart)
|
|
* [API 概览](/zh/api-playground/overview)
|
|
* [自定义组件](/zh/customize/react-components)
|
|
|
|
<div id="anchor-links">
|
|
## 锚点链接
|
|
</div>
|
|
|
|
锚点链接让你可以直接链接到页面中的特定部分。每个标题都会根据其文本自动生成一个锚点链接。
|
|
|
|
<div id="link-to-headers-on-the-same-page">
|
|
### 链接到同一页面中的标题
|
|
</div>
|
|
|
|
使用 hash 符号来引用本页的标题：
|
|
|
|
```mdx
|
|
[跳转至最佳实践](#best-practices)
|
|
```
|
|
|
|
[前往最佳实践](#best-practices)
|
|
|
|
<div id="link-to-headers-on-other-pages">
|
|
### 链接到其他页面中的标题
|
|
</div>
|
|
|
|
将页面路径与锚点链接拼接使用。
|
|
|
|
```mdx
|
|
* [自定义你的 API 演练场](/api-playground/overview#customize-your-playground)
|
|
* [Cards properties](/components/cards#properties)
|
|
```
|
|
|
|
* [自定义你的 Playground](/zh/api-playground/overview#customize-your-playground)
|
|
* [Cards 属性](/zh/components/cards#properties)
|
|
|
|
<div id="how-anchor-links-are-generated">
|
|
### 锚点链接是如何生成的
|
|
</div>
|
|
|
|
锚点链接会根据标题文本自动创建。
|
|
|
|
* 转换为小写形式
|
|
* 将空格替换为连字符
|
|
* 移除特殊字符
|
|
* 保留数字和字母
|
|
|
|
| 标题文本 | 锚点链接 |
|
|
|-------------|-------------|
|
|
| `## Getting Started` | `#getting-started` |
|
|
| `### API Authentication` | `#api-authentication` |
|
|
| `#### Step 1: Install` | `#step-1-install` |
|
|
|
|
<Note>
|
|
带有 `noAnchor` prop 的标题不会生成锚点链接。详情请参阅 [Format text](/zh/create/text#disabling-anchor-links)。
|
|
</Note>
|
|
|
|
<div id="link-to-api-endpoints">
|
|
## 链接到 API 端点
|
|
</div>
|
|
|
|
在编写 API 文档时，你可以在文档中的任何位置链接到特定端点。
|
|
|
|
通过它们在导航中的路径链接到对应的 API 端点页面。
|
|
|
|
<div id="link-to-external-pages">
|
|
## 链接到外部页面
|
|
</div>
|
|
|
|
在链接到外部资源时，应让用户清楚地知道该链接会跳转到文档之外的页面。
|
|
|
|
```mdx
|
|
了解更多关于 [Markdown 语法](https://www.markdownguide.org/)的信息(外部链接)。
|
|
|
|
有关详细信息,请参阅 Swagger 文档中的 [OpenAPI 规范](https://swagger.io/specification/)。
|
|
```
|
|
|
|
<div id="best-practices">
|
|
## 最佳实践
|
|
</div>
|
|
|
|
<div id="write-descriptive-link-text">
|
|
### 编写描述性链接文本
|
|
</div>
|
|
|
|
使用清晰、具体的文本，让用户一眼就知道链接会把他们带到哪里。
|
|
|
|
<CodeGroup>
|
|
```mdx Good examples
|
|
See [Hidden pages](/organize/hidden-pages) for more information.
|
|
[Configure custom domains](/customize/custom-domain)
|
|
```
|
|
|
|
```mdx Avoid
|
|
[Click here](/api-playground/overview)
|
|
[Read more](/deploy/deployments)
|
|
[See this page](/customize/custom-domain)
|
|
```
|
|
</CodeGroup>
|
|
|
|
<div id="create-topic-clusters">
|
|
### 创建主题集群
|
|
</div>
|
|
|
|
将相关内容相互链接起来，帮助用户发现相关信息。
|
|
|
|
```mdx
|
|
## 相关主题
|
|
|
|
- [API 认证](/api-playground/overview#authentication)
|
|
- [添加 SDK 示例](/api-playground/adding-sdk-examples)
|
|
- [管理页面可见性](/api-playground/managing-page-visibility)
|
|
```
|
|
|
|
<div id="use-contextual-links">
|
|
### 使用上下文链接
|
|
</div>
|
|
|
|
在内容中自然地添加链接，只在它们真正能提供价值的地方使用。
|
|
|
|
```mdx
|
|
要自定义文档外观,请在设置中配置[主题](/customize/themes)和[字体](/customize/fonts)。您还可以添加[自定义脚本](/customize/custom-scripts)以实现高级特性。
|
|
```
|
|
|
|
<div id="link-to-prerequisites">
|
|
### 链接到先决条件
|
|
</div>
|
|
|
|
通过链接到先决条件相关内容来帮助用户做好准备：
|
|
|
|
```mdx
|
|
## 前置条件
|
|
|
|
在部署文档之前,请确保您已:
|
|
|
|
- 完成[快速入门指南](/quickstart)
|
|
- 配置[自定义域名](/customize/custom-domain)
|
|
- 如有需要,设置[认证](/deploy/authentication-setup)
|
|
```
|
|
|
|
<div id="avoid-circular-links">
|
|
### 避免循环链接
|
|
</div>
|
|
|
|
不要创建会让用户在同一组页面之间反复来回跳转的链接。
|
|
|
|
<div id="check-for-broken-links">
|
|
### 检查失效链接
|
|
</div>
|
|
|
|
使用 Mintlify 命令行界面 (CLI) 检测文档中的失效链接。
|
|
|
|
```bash
|
|
mint broken-links
|
|
```
|
|
|
|
<div id="update-links-when-reorganizing">
|
|
### 在重新组织文档时更新链接
|
|
</div>
|
|
|
|
在移动或重命名页面时：
|
|
|
|
1. 在 navigation 配置中更新页面路径。
|
|
2. 为旧路径配置重定向到新路径。
|
|
3. 在文档中搜索所有对旧路径的引用。
|
|
4. 将所有内部链接更新为使用新路径。
|
|
5. 运行 `mint broken-links` 检查所有链接是否正常工作。
|
|
|
|
<div id="use-redirects-for-moved-content">
|
|
### 为已移动的内容设置重定向
|
|
</div>
|
|
|
|
在永久移动内容时，请添加重定向，避免出现无效链接。
|
|
|
|
```json
|
|
{
|
|
"redirects": [
|
|
{
|
|
"source": "/old-path",
|
|
"destination": "/new-path"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
详情请参阅[重定向](/zh/create/redirects)。
|
|
|
|
<div id="related-resources">
|
|
## 相关资源
|
|
</div>
|
|
|
|
* [格式化文本](/zh/create/text): 了解如何使用 Markdown 进行格式化。
|
|
* [导航](/zh/organize/navigation): 配置文档结构。
|
|
* [重定向](/zh/create/redirects): 为已移动的内容设置重定向。 |