Roteamento
Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system.
Routing in content pluginsβ
Every content plugin provides a routeBasePath
option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under /docs
; the blog plugin, /blog
; and the pages plugin, /
. You can think about the route structure like this:
Any route will be matched against this nested route config until a good match is found. For example, when given a route /docs/configuration
, Docusaurus first enters the /docs
branch, and then searches among the subroutes created by the docs plugin.
Changing routeBasePath
can effectively alter your site's route structure. For example, in Docs-only mode, we mentioned that configuring routeBasePath: '/'
for docs means that all routes that the docs plugin create would not have the /docs
prefix, yet it doesn't prevent you from having more subroutes like /blog
created by other plugins.
Next, let's look at how the three plugins structure their own "boxes of subroutes".
Pages routingβ
Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the pages docs for more information.
The component used for Markdown pages is @theme/MDXPage
. React pages are directly used as the route's component.
Blog routingβ
The blog creates the following routes:
- Posts list pages:
/
,/page/2
,/page/3
...- The component is
@theme/BlogListPage
.
- The component is
- Post pages:
/2021/11/21/algolia-docsearch-migration
,/2021/05/12/announcing-docusaurus-two-beta
...- Generated from each Markdown post.
- The routes are fully customizable through the
slug
front matter. - The component is
@theme/BlogPostPage
.
- Tags list page:
/tags
- The route is customizable through the
tagsBasePath
option. - The component is
@theme/BlogTagsListPage
.
- The route is customizable through the
- Tag pages:
/tags/adoption
,/tags/beta
...- Generated through the tags defined in each post's front matter.
- The routes always have base defined in
tagsBasePath
, but the subroutes are customizable through the tag'spermalink
field. - The component is
@theme/BlogTagsPostsPage
.
- Archive page:
/archive
- The route is customizable through the
archiveBasePath
option. - The component is
@theme/BlogArchivePage
.
- The route is customizable through the
Docs routingβ
The docs is the only plugin that creates nested routes. At the top, it registers version paths: /
, /next
, /2.0.0-beta.13
... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is @theme/DocPage
.
The individual docs are rendered in the remaining space after the navbar, footer, sidebar, etc. have all been provided by the DocPage
component. For example, this page, /pt-BR/docs/2.x/advanced/routing
, is generated from the file at ./versioned_docs/version-2.x/advanced/routing.md
. The component used is @theme/DocItem
.
The doc's slug
front matter customizes the last part of the route, but the base route is always defined by the plugin's routeBasePath
and the version's path
.
File paths and URL pathsβ
Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, ./docs/advanced/routing.md
will become /docs/advanced/routing
. However, with slug
, you can make URLs totally decoupled from the file structure.
When writing links in Markdown, you could either mean a file path, or a URL path, which Docusaurus would use several heuristics to determine.
- If the path has a
@site
prefix, it is always an asset file path. - If the path has an
http(s)://
prefix, it is always a URL path. - If the path doesn't have an extension, it is a URL path. For example, a link
[page](../plugins)
on a page with URL/docs/advanced/routing
will link to/docs/plugins
. Docusaurus will only detect broken links when building your site (when it knows the full route structure), but will make no assumptions about the existence of a file. It is exactly equivalent to writing<a href="../plugins">page</a>
in a JSX file. - If the path has an
.md(x)
extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path. - If the path has any other extension, Docusaurus would treat it as an asset and bundle it.
The following directory structure may help you visualize this file β URL mapping. Assume that there's no slug customization in any page.
A sample site structure
.
βββ 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