This is a note of the Docusaurus docs. Docusaurus is used to create and maintain web site. It is a single-page application powered by MDX and react. It supports multiple languages, versioning, theme and content search.

1. Architecture

Docusaurus has the following components:

  • Three content plugins: plugin-content-docs, plugin-content-blog, and plugin-content-pages. Plugins collect their content and emit JSON data. Plugin JS run in Node and use the require module syntax.
  • Two theme plugins: theme-classic, theme-live-codeblock. They provide layout components which receive the JSON data as route modules. Theme code uses ESM – folloiwng React conventions.
  • Two bundlers: server bundler and client bundler. they bundle all the components and emit a server bundle and a client bundle.

2. Plugins

A plugin is a function that takes two parameters context and options. It returns a plugin instance object or a promise. It is a convenient way to hook into the website’s build lifecycle to extend the config, modify data loaded and create new components to be used in a page. The loaded content will be available to the client side through actions like createData, addRoute or setGlobalData. This data has to be serialized to plain strings because it is generated in the server side but is used in client side.

Themes are plugins that provide the set of UI components to render the content. A plugin needs to be paired with a theme to be useful. Theme and content plugins share the same lifecycle methods.

3. Routing

Docusaurus builds a single-page application, where route transitions are done through the history.push() method of React router. Docusaurus' routing system follows SPA conventions: one route for one component.

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, /.

Pages routing is not customizalbe. It maps file paths directly to URLs. Pages use @theme/MDXPage component.

Blog routing has several routes:

  • Posts list: /, /page/2, /page/3… The component is @theme/BlogListPage.
  • Posts pages: /2021/11/21/post1. It is customizable with 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/react, /tags/dotnet. It is customizable through the tag’s permalink field. The component is @theme/BlogTagsPostsPage.
  • Archive page: /archive. It is customizable through the archiveBasePath option. The component is @theme/BlogArchivePage.

Docs routing defeins nested routes. At the top, it registers version paths: /, /next, /2.0.0-beta. 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. 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.

The addRoute lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. Docusaurus builds a single-page application, where route transitions are done through the history.push() method of React router.

4 Statis Site Generate (SSG)

The theme is built twice:

  • During server-side rendering, the theme is compiled in a sandbox called React DOM Server. You can see this as a “headless browser”, where there is no window or document, only React. SSR produces static HTML pages.
  • During client-side rendering, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript.

5 Client Architecture

A theme works by importing a set of components, e.g. Navbar, Layout, Footer, to render the data passed down from plugins. For example import Navbar from '@theme/Navbar';. The alias @theme can refer to a few directories, in the following priority:

  • A user’s /src/theme directory, which is a special directory that has the higher precedence.
  • A Docusaurus theme package’s theme directory.
  • Fallback components provided by Docusaurus core (usually not needed).

This is called a layered architecture: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. the “userland theme” in src/theme can re-use a theme component through the @theme-original alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the @theme-init import.

6 Use Guides

6.1 Pages

The @docusaurus/plugin-content-pages plugin empowers you to create one-off standalone pages like a showcase page, playground page, or support page. You can use React components, or Markdown. By default, any folder, Markdown or JavaScript file starting with _ will be ignored and no routes will be created for that file.

6.2 Docs

The docs feature provides users with a way to organize Markdown files in a hierarchical format.

Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory. For example, greeting.md id is greeting and guide/hello.md id is guide/hello. However, the last part of the id can be defined by the user in the id front matter. Use the slug front matter to change a document’s URL. the slug: / defines a home at the root.

Tags are passed in the front matter as a list of labels:

1
2
3
4
5
6
7
---
id: doc-with-tags
title: A doc with tags
tags:
  - Demo
  - Getting started
---

Tags can also be declared with tags: [Demo, Getting started]. Use the category type to create a hierarchy of sidebar items. You can auto-generate an index page that displays all the direct children of this category. The slug allows you to customize the generated page’s route, which defaults to /category/[categoryName].

Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.