Skip to main content
Version: 3.5.1

Markdown 链接

¥Markdown links

有两种方法可以添加到另一个页面的链接：通过 URL 路径和文件路径。

¥There are two ways of adding a link to another page: through a URL path and a file path.

- [URL path to another document](./installation)
- [file path to another document](./installation.mdx)

Docusaurus 未处理 URL 路径，你可以将它们视为直接渲染到 <a href="./installation">，即它将根据页面的 URL 位置而不是其文件系统位置进行解析。

¥URL paths are unprocessed by Docusaurus, and you can see them as directly rendering to <a href="./installation">, i.e. it will be resolved according to the page's URL location, rather than its file-system location.

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

¥If you want to reference another Markdown file included by the same plugin, you could use the relative path of the document you want to link to. Docusaurus' Markdown loader will convert the file path to the target file's URL path (and hence remove the .md extension).

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

¥For example, if you are in docs/folder/doc1.md and you want to reference docs/folder/doc2.md, docs/folder/subfolder/doc3.md and docs/otherFolder/doc4.md:

docs/folder/doc1.md
I am referencing a [document](doc2.mdx).

Reference to another [document in a subfolder](subfolder/doc3.mdx).

[Relative document](../otherFolder/doc4.mdx) referencing works as well.

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

¥Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the content root, usually docs/, blog/, or localized ones like i18n/zh-Hans/plugin-content-docs/current.

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

¥Absolute file paths can also be relative to the site directory. However, beware that links that begin with /docs/ or /blog/ are not portable as you would need to manually update them if you create new doc versions or localize them.

You can write [links](/otherFolder/doc4.mdx) relative to the content root (`/docs/`).

You can also write [links](/docs/otherFolder/doc4.mdx) relative to the site directory, but it's not recommended.

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

¥Using relative file paths (with .md extensions) instead of relative URL links provides the following benefits:

  • 链接将在 GitHub 界面和许多 Markdown 编辑器上继续有效

    ¥Links will keep working on the GitHub interface and many Markdown editors

  • 你可以自定义文件的 slugs，而无需更新所有链接

    ¥You can customize the files' slugs without having to update all the links

  • 你的编辑器可以跟踪在文件夹中移动文件，并且某些编辑器可能会自动更新文件链接

    ¥Moving files around the folders can be tracked by your editor, and some editors may automatically update file links

  • 版本化文档 将链接到完全相同版本的另一个文档

    ¥A versioned doc will link to another doc of the exact same version

  • 如果你更新 trailingSlash 配置，相对 URL 链接很可能会损坏

    ¥Relative URL links are very likely to break if you update the trailingSlash config

警告

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

¥Markdown file references only work when the source and target files are processed by the same plugin instance. This is a technical limitation of our Markdown processing architecture and will be fixed in the future. If you are linking files between plugins (e.g. linking to a doc page from a blog post), you have to use URL links.