Skip to main content

ルーティング

Docusaurus のルーティングシステムは、1つのルートに1つのコンポーネントというシングルページアプリケーションの規約に従っています。 このセクションでは、ドキュメント、ブログ、ページといった3つのコンテンツプラグイン内のルーティングについて説明し、内部のルーティングシステムについて話を進めます。

コンテンツプラグインのルーティング​

Every content plugin provides a routeBasePath option. プラグインがどこのルートに追加されるかを定義するものです。 By default, the docs plugin puts its routes under /docs; the blog plugin, /blog; and the pages plugin, /. ルート構造は次のように考えることができます。

ルートはこのネストされたルート設定に照らして順に照合され、適切なマッチが見つかるまで検索が続きます。 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.

次に、3つのプラグインがそれぞれどのように「サブルートの枠組み」を構築しているかを見てみましょう。

ページのルーティング​

ページのルーティングはシンプルで、ファイルのパスがそのままURLに対応し、カスタマイズ方法はほとんどありません。 See the pages docs for more information.

The component used for Markdown pages is @theme/MDXPage. Reactページは、そのままルートのコンポーネントとして使用されます。

ブログのルーティング​

ブログは以下のルートを作成します：

  • Posts list pages: /, /page/2, /page/3...
    • The route is customizable through the pageBasePath option.
    • The component is @theme/BlogListPage.
  • Post pages: /2021/11/21/algolia-docsearch-migration, /2021/05/12/announcing-docusaurus-two-beta...
    • 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...
    • 各投稿のフロントマターで定義されたタグから生成されます。
    • 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.

ドキュメントのルーティング​

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. これにより、個別のドキュメント間を移動してもサイドバーの状態が保持され、ナビゲーションバーのドロップダウンからバージョンを切り替えても、同じドキュメント上に留まることができます。 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. 例えば、このページ <URLPath /> は、ファイル <FilePath /> から生成されています。 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.

ファイルのパスと URL のパス​

ドキュメント全体を通して、ファイルパスと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.
  • パスに拡張子がない場合は URL のパスになります。 For example, a link [page](../plugins) on a page with URL /docs/advanced/routing will link to /docs/plugins. Docusaurus はサイトをビルドするときに (完全なルート構造を知っている場合) のみリンク切れを検出します。ファイルの存在は想定しません。 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.

以下のディレクトリ構成は、ファイルからURLへのマッピングをイメージしやすくするためのものです。 すべてのページで slug のカスタマイズがないものとします。

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/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はサーバーサイドレンダリング（SSR）フレームワークのため、生成されるすべてのルートはサーバーサイドでレンダリングされ、静的なHTMLファイルとして出力されます。 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. ホスティングプロバイダーによっては、末尾のスラッシュの有無で両者を区別し、どちらか一方のみを許容する場合があります。 Read more in the trailing slash guide.

例えば、上記ディレクトリ構成のビルド出力は以下のようになります（その他のアセットや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.

ローカライズされたサイトでは、ロケールが base URL の一部として含まれます。 For example, https://docusaurus.io/zh-CN/docs/advanced/routing/ has base URL /zh-CN/.

ルートの生成とアクセス​

The addRoute lifecycle action is used to generate routes. ルートツリーにルート設定の一部を登録し、ルートやコンポーネント、そしてそのコンポーネントが必要とするプロパティを指定します。 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. （機能的には似ていますが、ブラウザのAPIとは厳密には異なります。 詳しいAPIについては、React Routerのドキュメントを参照してください）

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 /ja/docs/advanced/routing

SPA のリダイレクトを回避する​

Docusaurus builds a single-page application, where route transitions are done through the history.push() method of React router. この操作はクライアント側で行われます。 ただし、この方法でルート遷移が行われるためには、遷移先のURLがDocusaurusのルーターに認識されている必要があります。 そうでない場合、ルーターはそのパスを検知して404ページを表示します。

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.

- [pathname:///pure-html](pathname:///pure-html)
http://localhost:3000

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
![An image from the static](pathname:///img/docusaurus.png)

[An asset from the static](pathname:///files/asset.pdf)

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