---
title: 链接与导航
description: 在页面之间建立链接、定位到特定标题，并引用外部 URL；包括 Card 导航和断链检查。
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
MDX 支持标准 Markdown 链接，以及 Jamdesk 用于页面间链接、定位标题和引用外部 URL 的专用模式。
## 内部链接
使用相对路径链接到文档中的其他页面：
```markdown
Read the [getting started guide](/quickstart) first.
See the [Card component](/components/card) for more options.
```
使用相对于文档根目录的路径，不要包含 `.mdx` 扩展名。
### 链接到标题
使用锚点链接直接链接到某个部分：
```markdown
See [configuration options](/config/docs-json-reference#colors)
```
标题会根据其文本自动生成锚点：
- `## Getting Started` → `#getting-started`
- `## API Reference` → `#api-reference`
## 外部链接
链接到外部网站：
```markdown
Check the [GitHub repository](https://github.com/example/repo).
```
外部链接会自动在新标签页中打开，并启用安全设置。
## 使用 Card 创建链接
对于醒目的导航，请使用 Card，而不是内联链接：
```mdx
Get up and running in 5 minutes
```
在 5 分钟内完成设置并开始使用
### Card 组
将相关链接组合在一起：
```mdx
Install the CLI
Configure your project
```
安装 CLI
配置项目
## 最佳实践
告诉读者链接的目标位置：
```markdown
{/* Good */}
Learn more in our [authentication guide](/quickstart).
{/* Avoid */}
For more info, [click here](/quickstart).
```
链接到最具体的相关部分：
```markdown
{/* Good - links to specific section */}
Configure [OAuth settings](/quickstart#whats-next).
{/* Less helpful - links to entire page */}
See the [auth docs](/quickstart) for OAuth settings.
```
断开的链接会让读者感到困扰。请定期运行链接检查：
```bash
jamdesk broken-links
```
此命令会扫描文档并报告所有断开的内部链接。
## 检查断开的链接
Jamdesk CLI 可以扫描断开的链接：
```bash
jamdesk broken-links
```
示例输出：
```text
docs/getting-started.mdx:15 - /docs/quikstart
Did you mean: /docs/quickstart
Found 1 broken link in 45 files.
```
在部署前运行此命令，以发现拼写错误和过时的引用。
### 自动修复断开的链接
当断开的链接存在明确无误的正确目标时（例如锚点拼写错误，或翻译页面重命名标题导致跨语言锚点漂移），`jamdesk fix` 会自动为你修复：
```bash
jamdesk fix --dry-run # preview every planned fix, write nothing
jamdesk fix # apply after a y/N confirmation
```
只有当修正后的锚点确实是目标页面上的标题时，该命令才会改写链接；任何存在歧义的链接都会保留，以便手动检查。请参阅[自动修复断开的链接](/cn/cli/fix-broken-links)。
### 如何检测内部链接
不包含 `https://` 的链接会被视为内部链接，并根据文档页面进行验证。验证器会检查目标页面是否存在于 `docs.json` 导航中。
对于使用 `hostAtDocs` 的网站（文档托管在 `/docs` 等子路径下），运行时会**自动添加前缀**到内部链接。请填写相对于文档根目录的路径；系统会自动为你添加 `/docs` 前缀：
```markdown
{/* Just write the docs path — auto-prefixed to /docs/config/docs-json-reference */}
See the [Reference](/config/docs-json-reference).
```
非文档链接（例如营销页面）应使用完整 URL：`https://example.com/pricing`。
文档内容中的任何 `/path` 链接都会被视为内部文档链接。
## 重命名页面
重命名页面时，链接会失效。使用 CLI 更新所有引用：
```bash
jamdesk rename api/old-name.mdx api/new-name.mdx
```
此命令会自动：
- 重命名文件
- 更新 `docs.json` 导航
- 修复其他所有页面中的链接
## 下一步
改善内容发现和元数据
定义标题、描述和 SEO 字段