Routage

Le système de routage de Docusaurus suit les conventions d'une application mono-page : une route, un composant. Dans cette section, nous commencerons par parler du routage dans les trois plugins de contenu (docs, blog et pages), puis nous irons plus loin pour parler du système de routage sous-jacent.

Routing in content plugins

Every content plugin provides a routeBasePath option. Cela définit où les plugins ajoutent leurs routes. By default, the docs plugin puts its routes under /docs; the blog plugin, /blog; and the pages plugin, /. Vous pouvez considérer la structure de la route comme suit :

Toute route sera comparée à cette configuration de route imbriquée jusqu'à ce qu'une bonne correspondance soit trouvée. 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.

Voyons ensuite comment les trois plugins structurent leurs propres « boîtes de sous-routes ».

Pages routing

Le routage des pages est simple : les chemins de fichiers correspondent directement aux URL, sans autre possibilité de personnalisation. See the pages docs for more information.

The component used for Markdown pages is @theme/MDXPage. Les pages React sont directement utilisées comme composant de la route.

Blog routing

Le blog crée les routes suivantes :

• Posts list pages: /, /page/2, /page/3...
  • The component is @theme/BlogListPage.
• Post pages: /2021/11/21/algolia-docsearch-migration, /2021/05/12/announcing-docusaurus-two-beta...
  • Généré à partir de chaque article Markdown.
  • 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.
• Tag pages: /tags/adoption, /tags/beta...
  • Généré à travers les tags définis dans chaque front matter des articles.
  • The routes always have base defined in tagsBasePath, but the subroutes are customizable through the tag's permalink field.
  • The component is @theme/BlogTagsPostsPage.
• Archive page: /archive
  • The route is customizable through the archiveBasePath option.
  • The component is @theme/BlogArchivePage.

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. Ainsi, lorsque vous passez d'un document à l'autre, l'état de la barre latérale est préservé et vous pouvez passer d'une version à l'autre via la barre de navigation déroulante tout en restant sur le même document. 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. Par exemple, cette page, /fr/docs/advanced/routing, est générée à partir du fichier ./versioned_docs/version-2.4.0/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

Dans toute la documentation, nous essayons toujours d'être sans ambiguïté quant à savoir si nous parlons de chemins de fichiers ou de chemins d'URL. 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.
• Si le chemin n'a pas d'extension, c'est un chemin d'URL. For example, a link [page](../plugins) on a page with URL /docs/advanced/routing will link to /docs/plugins. Docusaurus ne détectera les liens cassés que lors de la construction de votre site (lorsqu'il connaît la structure complète de la route), mais ne fera aucune supposition quant à l'existence d'un fichier. 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.

La structure de répertoire suivante peut vous aider à visualiser le mappage de ce fichier vers l'URL. En supposant qu'il n'y a pas de personnalisation de slug dans aucune 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
│       ├── 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/congratulations
│   └── 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/congratulations
        └── 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

Voilà pour les plugins de contenu. Prenons un peu de recul et parlons de la façon dont le routage fonctionne dans une application Docusaurus en général.

Routes become HTML files

Comme Docusaurus est un framework de rendu côté serveur, toutes les routes générées seront affichées côté serveur en fichiers HTML statiques. If you are familiar with the behavior of HTTP servers like Apache2, you will understand how this is done: when the browser sends a request to the route /docs/advanced/routing, the server interprets that as request for the HTML file /docs/advanced/routing/index.html, and returns that.

The /docs/advanced/routing route can correspond to either /docs/advanced/routing/index.html or /docs/advanced/routing.html. Certains hébergeurs font la différence entre eux en utilisant la présence d'un slash final et peuvent ou non tolérer l'autre. Read more in the trailing slash guide.

Par exemple, le résultat de la construction du répertoire ci-dessus est (en ignorant les autres ressources et le bundle JS) :

Output of the above workspace

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/

If trailingSlash is set to false, the build would emit intro.html instead of intro/index.html.

All HTML files will reference its JS assets using absolute URLs, so in order for the correct assets to be located, you have to configure the baseUrl field. Note that baseUrl doesn't affect the emitted bundle's file structure: the base URL is one level above the Docusaurus routing system. You can see the aggregate of url and baseUrl as the actual location of your Docusaurus site.

For example, the emitted HTML would contain links like <link rel="preload" href="/assets/js/runtime~main.7ed5108a.js" as="script">. Because absolute URLs are resolved from the host, if the bundle placed under the path https://example.com/base/, the link will point to https://example.com/assets/js/runtime~main.7ed5108a.js, which is, well, non-existent. By specifying /base/ as base URL, the link will correctly point to /base/assets/js/runtime~main.7ed5108a.js.

Sur les sites localisés, la locale fait également partie de l'URL de base. For example, https://docusaurus.io/zh-CN/docs/advanced/routing/ has base URL /zh-CN/.

Generating and accessing routes

The addRoute lifecycle action is used to generate routes. Il enregistre un morceau de configuration de route dans l'arborescence des routes, en donnant une route, un composant et les props dont le composant a besoin. The props and the component are both provided as paths for the bundler to require, because as explained in the architecture overview, server and client only communicate through temp files.

All routes are aggregated in .docusaurus/routes.js, which you can view with the debug plugin's routes panel.

On the client side, we offer @docusaurus/router to access the page's route. @docusaurus/router is a re-export of the react-router-dom package. For example, you can use useLocation to get the current page's location, and useHistory to access the history object. (Ils ne sont pas identiques à l'API du navigateur, bien que leur fonctionnalité soit similaire. Reportez-vous à la documentation de React Router pour les API spécifiques.)

This API is SSR safe, as opposed to the browser-only window.location.

myComponent.js

import React from 'react';
import {useLocation} from '@docusaurus/router';

export function PageRoute() {
  // React router provides the current component's route, even in SSR
  const location = useLocation();
  return (
    <span>
      We are currently on <code>{location.pathname}</code>
    </span>
  );
}

http://localhost:3000

We are currently on /fr/docs/advanced/routing

Escaping from SPA redirects

Docusaurus builds a single-page application, where route transitions are done through the history.push() method of React router. Cette opération se fait du côté client. Cependant, la condition préalable pour qu'une transition de route se produise de cette manière est que l'URL cible soit connue de notre routeur. Sinon, le routeur intercepte ce chemin et affiche une page 404 à la place.

If you put some HTML pages under the static folder, they will be copied to the build output and therefore become accessible as part of your website, yet it's not part of the Docusaurus route system. We provide a pathname:// protocol that allows you to redirect to another part of your domain in a non-SPA fashion, as if this route is an external link. Essayez les deux liens suivants :

- [/pure-html](/pure-html)
- [pathname:///pure-html](pathname:///pure-html)

http://localhost:3000

• /pure-html
• pathname:///pure-html

astuce

The first link will not trigger a "broken links detected" check during the production build, because the respective file actually exists. Néanmoins, lorsque vous cliquez sur le lien, une « page introuvable » s'affichera jusqu'à ce que vous rafraîchissiez.

The pathname:// protocol is useful for referencing any content in the static folder. For example, Docusaurus would convert all Markdown static assets to require() calls. You can use pathname:// to keep it a regular link instead of being hashed by Webpack.

my-doc.md

![Une image depuis static](pathname:///img/docusaurus.png)

[Une ressource depuis static](pathname:///files/asset.pdf)

Docusaurus will only strip the pathname:// prefix without processing the content.