Markdown 链接
有两种方法添加一个指向其他页面的链接:URL 路径或者文件路径。
- [URL path to another document](./installation)
- [file path to another document](./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
:
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.
相对文件路径会基于当前文件的目录解析。 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/
开头的链接是难以转移的,因为如果你创建了新的文档版本或者翻译了它们,你会需要手动更新它们。
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 路径提供了以下好处:
- 链接能在 GitHub 界面和许多 Markdown 编辑器里工作
- 你可以自定义文件的 slug,而不必更新所有链接
- 文件在不同文件夹之间的移动可以被你的编辑器追踪,而且一些编辑器可以自动更新文件链接
- A versioned doc will link to another doc of the exact same version
- Relative URL links are very likely to break if you update the
trailingSlash
config
Markdown 文件链接仅在源文件和目标文件是被同一个插件实例所处理的时候才能工作。 这是我们 Markdown 处理架构的技术限制,会在以后被修复。 如果你的链接跨越了两个插件(例如在一篇博客帖子中链接到一个文档页面),你必须用 URL 链接。