Skip to main content

Markdown 链接

添加指向另一个页面的链接有两种方式：通过 URL 路径和文件路径。

- [指向另一个文档的 URL 路径](./installation)
- [指向另一个文档的文件路径](./installation.mdx)

URL 路径不会被道格龙（Docusaurus）处理，你可以将其看作直接渲染为 <a href="./installation">，也就是说，它将根据页面的 URL 位置进行解析，而不是其文件系统位置。

如果你想引用由同一插件包含的另一个 Markdown 文件，你可以使用你想要链接到的文档的相对路径。道格龙（Docusaurus）的 Markdown 加载器会将文件路径转换为目标文件的 URL 路径（因此会移除 .md 扩展名）。

例如，如果你在 docs/folder/doc1.md 中，并且想要引用 docs/folder/doc2.md、docs/folder/subfolder/doc3.md 和 docs/otherFolder/doc4.md：

docs/folder/doc1.md
我正在引用一个[文档](doc2.mdx)。

引用另一个[在子文件夹中的文档](subfolder/doc3.mdx)。

[相对文档](../otherFolder/doc4.mdx)的引用方式也同样有效。

相对文件路径是相对于当前文件所在目录进行解析的。而绝对文件路径则是相对于内容根目录进行解析，通常是 docs/、blog/，或本地化目录如 i18n/zh-Hans/plugin-content-docs/current。

绝对文件路径也可以相对于站点目录。但是，请注意以 /docs/ 或 /blog/ 开头的链接不具有可移植性，因为如果你创建新的文档版本或对其进行本地化，你需要手动更新它们。

你可以编写相对于内容根目录 (`/docs/`) 的[链接](/otherFolder/doc4.mdx)。

你也可以编写相对于站点目录的[链接](/docusaurus/otherFolder/doc4.mdx)，但不推荐这样做。

使用相对文件路径（带 .md 扩展名）而不是相对 URL 链接有以下好处：

  • 链接在 GitHub 界面和许多 Markdown 编辑器中将保持可用
  • 你可以自定义文件的 URL 别名（slug），而无需更新所有链接
  • 在文件夹之间移动文件可以被你的编辑器跟踪，一些编辑器可能会自动更新文件链接
  • 一个版本化的文档将链接到完全相同版本的另一个文档
  • 如果你更新 trailingSlash 配置，相对 URL 链接很可能会失效
warning

Markdown 文件引用仅在源文件和目标文件由同一个插件实例处理时才有效。这是我们 Markdown 处理架构的一个技术限制，并将在未来修复。如果你在不同插件之间链接文件（例如，从博客文章链接到文档页面），你必须使用 URL 链接。

Last updated on