docmd 提供了一个强大的、具有文件系统感知能力的链接系统。你可以自然地编写指向源 .md 文件的链接 —— 使用你喜欢的任何格式 —— 引擎会自动将它们规范化为干净、经过 SEO 优化的生产环境 URL。

URL 规范化是如何工作的

在构建过程中，引擎会对每一个内部链接（包括 Markdown 文本、按钮容器、标签和导航配置中的链接）应用一套一致的规则：

内部链接解析

使用指向源 .md 文件的相对路径来链接到文档中的其他页面。无论目录深度如何，引擎都能正确解析它们。

章节锚点 (深层链接)

使用标准的 URL 哈希片段直接导航到特定标题。

• 页内锚点: [跳转到路线图](#project-roadmap)
• 跨页锚点: [查看 CLI 标志](../cli-commands.md#available-flags)

哈希片段在规范化过程中会被保留。上面的链接在生产环境中渲染为 ../cli-commands/#available-flags。

在新标签页中打开链接

在任何链接上使用 external: 前缀强制其在新标签页中打开。这在标准 Markdown 链接、按钮容器、标签以及任何可以编写 URL 的地方都是通用的。

<!-- 强制任何链接在新标签页中打开 -->
[在新标签页中打开](external:./configuration/overview.md)

<!-- 指向 GitHub 的外部链接 -->
[GitHub](external:https://github.com/docmd-io/docmd)

默认情况下，所有链接（包括 HTTP/HTTPS）都在同一个窗口中打开。仅当你想要一个新标签页时才使用 external: 前缀。

external: 前缀会从渲染后的 URL 中 剥离 —— 它纯粹是一个构建时信号。

链接到原始文件

默认情况下，引擎会剥离 .md 扩展名并规范化路径。如果你确实需要链接到原始 .md 文件（例如，可下载的源文件），请使用 raw: 前缀：

[查看原始源码](raw:docs/readme.md)

raw: 前缀会绕过所有规范化 —— 扩展名和路径将完全按照编写的方式保留。与 external: 一样，前缀本身会从渲染后的 URL 中剥离。

按钮容器 (Button Containers)

::: button 容器支持与标准 Markdown 链接相同的链接约定 —— 包括 external: 和 raw: 前缀：

::: button "开始使用" ./getting-started/quick-start.md icon:rocket

::: button "在 GitHub 上查看" https://github.com/docmd-io/docmd icon:github

::: button "下载源码" raw:docs/readme.md icon:download

标签链接 (Tag Links)

带有 link: 值的标签也受益于统一规范化器：

::: tag "v0.7.6" link:release-notes/0-7-6.md icon:tag color:#22c55e

::: tag "GitHub" link:https://github.com/docmd-io/docmd icon:github

::: tag "从外部打开" link:external:./configuration/overview.md icon:external-link

导航配置

在 navigation.json 和 docmd.config.js 中定义的路径也会在构建时进行规范化。你可以使用任何格式编写它们：

[
  { "title": "Overview", "path": "configuration/overview" },
  { "title": "Overview", "path": "configuration/overview.md" },
  { "title": "Overview", "path": "configuration/overview/" }
]

上面的三个条目都会生成相同的规范 URL：/configuration/overview/。

对于应该在新标签页中打开的导航项目，请使用 external 标志：

[
  {
    "title": "GitHub",
    "path": "https://github.com/docmd-io/docmd",
    "external": true
  }
]

<!-- 推荐 -->
[本地化](localisation/)

<!-- 同样有效（自动规范化） -->
[本地化](localisation/index.md)

协议与外部资源

引擎尊重标准浏览器的外部资源协议。这些链接永远不会被修改。

• 全局 HTTPS: [docmd 主页](https://docmd.io) —— 在同一个标签页中打开（使用 external: 前缀以在新标签页中打开）
• 邮件协议: [支持渠道](mailto:help@docmd.io) —— 不在新标签页中打开
• 资源协议: [下载 CLI 二进制文件](/assets/bin/docmd-mac.zip) —— 不进行规范化

静态资源引用

要提供下载或引用原始源文件，请将它们放在项目的 assets/ 目录中。docmd 构建器确保这些文件被移动到生产根目录，且不修改路径。

[下载文档 PDF](/assets/pdf/handbook.pdf)
[查看原始全局配置](/assets/config/docmd.config.js)