路由
Docusaurus 的路由系统遵循单页应用的传统:一个路由对应一个组件。 在本节中,我们会首先讨论三个内容插件(文档、博客和页面)所创建的路由,然后再讨论底层的路由系统。
内容插件创建的路由
每个内容插件都提供 一个 routeBasePath
选项。 它定义了插件创造的路径的公共前缀。 默认情况下,文档插件的路径会以 /docs
开头;博客插件以 /blog
开头;页面插件则以 /
开头。 你可以想象这样的路由结构:
所有路径都会与这个嵌套路由配置匹配,直到找到一个恰当的匹配。 比如,给定路径 /docs/configuration
,Docusaurus 会进入 /docs
分支,然后在文档插件创建的子路径中搜索。
更改 routeBasePath
可以有效改变网站的路由结构。 比如,在仅文档模式中,我们提到,为文档配置 routeBasePath: '/'
意味着文档插件创建的所有路由都没有 /docs
前缀,然而它并不会阻止其他插件创建更多的子路由,比如 /blog
。
接下来,让我们看看这三个插件是如何构建它们自己的「子路由盒子」的。
页面路由
页面路由非常简单:文件路径直接映射到 URL,没有其他方法自定义。 更多信息请参阅页面文档。
Markdown 页面使用的组件是 @theme/MDXPage
。 React 页面会被直接用作路由组件。
博客路由
博客会创建以下路径:
- 帖子列表页面:
/
、/page/2
、/page/3
……- 路径可以通过
pageBasePath
选项自定义。 - 组件是
@theme/BlogListPage
。
- 路径可以通过
- 帖子页面:
/2021/11/21/algolia-docsearch-migration
、/2021/05/12/announcing-docusaurus-two-beta
……- 通过每个 Markdown 文件生成。
- 路径可以通过
slug
前言完全自定义。 - 组件是
@theme/BlogPostPage
。
- 标签列表页:
/tags
- 路径可以通过
tagsBasePath
选项自定义。 - 组件是
@theme/BlogTagsListPage
。
- 路径可以通过
- 标签页:
/tags/adoption
、/tags/beta
……- 通过每个帖子的
tags
前言定义的标签生成。 - 路径的前缀通过
tagsBasePath
定义,但子路径可以通过标签的permalink
字段自定义。 - 组件是
@theme/BlogTagsPostsPage
。
- 通过每个帖子的
- 总览页:
/archive
- 路径 可以通过
archiveBasePath
选项自定义。 - 组件是
@theme/BlogArchivePage
。
- 路径 可以通过
文档路由
文档插件是唯一一个会创建嵌套路由的插件。 它会在顶部注册版本路径:/
、/next
、/2.0.0-beta.13
……这些路径提供了版本的语境,包括布局和侧边栏等。 这确保了在切换文档时,侧边栏的状态能够保持,并且你可以通过导航栏下拉菜单切换版本,同时保持在同一篇文档上。 使用的组件是 @theme/DocPage
。
Docpage
组件提供了导航栏、页脚、侧边栏等布局,而单个文档会在它们剩下的空间中渲染。 比如这个页面,/zh-CN/docs/next/advanced/routing
,就是通过位于 ./docs/advanced/routing.md
的文件生成的。 这一部分使用的组件是 @theme/DocItem
。
文档的 slug
前言可以自定义路由的最后一部分, 但路径前缀总是由插件的 routeBasePath
和版本的 path
决定的。
文件路径和 URL 路径
在所有文档中,我们一直在试图明确当前讨论的是文件路径还是 URL 路径。 内容插件通常会直接把文件路径映射到 URL 路径。比如 ./docs/advanced/routing.md
文件就会变成 /docs/advanced/routing
。 然而,通过 slug
前言,你可以让 URL 和文件结构完全脱钩。
在 Markdown 中书写链接时,你既可能指_文件路径_, 也可能指 URL 路径,Docusaurus 会通过几个原则来确定你指的是哪个。
- 如果路径包含
@site
前缀,它_永远_是文件资源路径。 - 如果路径包含
http(s)://
前缀,它_永远_是 URL 路径。 - 如果路径没有扩展名,它会被当做 URL 路径。 比如一个页面的 URL 是
/docs/advanced/routing
,它包含一个[page](../plugins)
的链接,那么链接会指向/docs/plugins
。 Docusaurus 只会在构建网站时做无效链接检测(因为这时候它知道所有的路由架构),但它不会假设有对应文件的存在。 这和在 JSX 文件中写<a href="../plugins"> page</a>
完全等价。 - 如果路径包含
.md(x)
扩展名,Docusaurus 会尝试把这个 Markdown 文件路径解析到一个 URL,并将文件路径替换为 URL 路径。 - 如果路径有任何其它扩展名,Docusaurus 会将它视为资源文件并把它打包。
下面这个文件目录可能能帮你可视化这种文件 → URL 的映射。 假设所有页面都没有自定义的 Slug。
网站结构示例
.
├── blog # blog plugin has routeBasePath: '/blog'
│ ├── 2019-05-28-first-blog-post.md # -> /blog/2019/05/28/first-blog-post
│ ├── 2019-05-29-long-blog-post.md # -> /blog/2019/05/29/long-blog-post
│ ├── 2021-08-01-mdx-blog-post.mdx # -> /blog/2021/08/01/mdx-blog-post
│ └── 2021-08-26-welcome
│ ├── docusaurus-plushie-banner.jpeg
│ └── index.md # -> /blog/2021/08/26/welcome
├── docs # docs plugin has routeBasePath: '/docs'; current version has base path '/'
│ ├── intro.md # -> /docs/intro
│ ├── tutorial-basics
│ │ ├── _category_.json
│ │ ├── congratulations.md # -> /docs/tutorial-basics/congratulations
│ │ └── markdown-features.mdx # -> /docs/tutorial-basics/markdown-features
│ └── tutorial-extras
│ ├── _category_.json
│ ├── manage-docs-versions.md # -> /docs/tutorial-extras/manage-docs-versions
│ └── translate-your-site.md # -> /docs/tutorial-extras/translate-your-site
├── src
│ └── pages # pages plugin has routeBasePath: '/'
│ ├── index.module.css
│ ├── index.tsx # -> /
│ └── markdown-page.md # -> /markdown-page
└── versioned_docs
└── version-1.0.0 # version has base path '/1.0.0'
├── intro.md # -> /docs/1.0.0/intro
├── tutorial-basics
│ ├── _category_.json
│ ├── congratulations.md # -> /docs/1.0.0/tutorial-basics/congratulations
│ └── markdown-features.mdx # -> /docs/1.0.0/tutorial-basics/markdown-features
└── tutorial-extras
├── _category_.json
├── manage-docs-versions.md # -> /docs/1.0.0/tutorial-extras/manage-docs-versions
└── translate-your-site.md # -> /docs/1.0.0/tutorial-extras/translate-your-site
关于内容插件,就讲这么多。 让我们后退一步,总地谈谈 Docusaurus 应用中路由是怎么工作的。
路径会变成 HTML 文件
因为 Docusaurus 是一个服务端渲染的框架,所以生成的所有路由都将被渲染为静态 HTML 文件。 如果你熟悉 HTTP 服务器的行为,比如 Apache2, 你就能理解这是怎么工作的:当浏览器向 /docs/advanced/routing
这个路径发送请求时,服务器会把这个路径解释为对 /docs/advanced/routing/index.html
这个 HTML 文件的请求,并返回此文件。
/docs/advanced/routing
路径可能对应 /docs/advanced/routing/index.html
或者 /docs/advanced/routing.html
两个文件。 有些网站托管服务会通过 URL 是否在末尾有一个斜杠对它们加以区分,然后既可能接受另一种 URL,也可能不接受。 你可以在末尾斜杠指南中阅读更多。
比如,上面的文件目录的会有以下构建输出(略去其他资源和 JS 文件):
上述项目的输出
build
├── 404.html # /404/
├── blog
│ ├── archive
│ │ └── index.html # /blog/archive/
│ ├── first-blog-post
│ │ └── index.html # /blog/first-blog-post/
│ ├── index.html # /blog/
│ ├── long-blog-post
│ │ └── index.html # /blog/long-blog-post/
│ ├── mdx-blog-post
│ │ └── index.html # /blog/mdx-blog-post/
│ ├── tags
│ │ ├── docusaurus
│ │ │ └── index.html # /blog/tags/docusaurus/
│ │ ├── hola
│ │ │ └── index.html # /blog/tags/hola/
│ │ └── index.html # /blog/tags/
│ └── welcome
│ └── index.html # /blog/welcome/
├── docs
│ ├── 1.0.0
│ │ ├── intro
│ │ │ └── index.html # /docs/1.0.0/intro/
│ │ ├── tutorial-basics
│ │ │ ├── congratulations
│ │ │ │ └── index.html # /docs/1.0.0/tutorial-basics/congratulations/
│ │ │ └── markdown-features
│ │ │ └── index.html # /docs/1.0.0/tutorial-basics/markdown-features/
│ │ └── tutorial-extras
│ │ ├── manage-docs-versions
│ │ │ └── index.html # /docs/1.0.0/tutorial-extras/manage-docs-versions/
│ │ └── translate-your-site
│ │ └── index.html # /docs/1.0.0/tutorial-extras/translate-your-site/
│ ├── intro
│ │ └── index.html # /docs/1.0.0/intro/
│ ├── tutorial-basics
│ │ ├── congratulations
│ │ │ └── index.html # /docs/tutorial-basics/congratulations/
│ │ └── markdown-features
│ │ └── index.html # /docs/tutorial-basics/markdown-features/
│ └── tutorial-extras
│ ├── manage-docs-versions
│ │ └── index.html # /docs/tutorial-extras/manage-docs-versions/
│ └── translate-your-site
│ └── index.html # /docs/tutorial-extras/translate-your-site/
├── index.html # /
└── markdown-page
└── index.html # /markdown-page/