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.
Docusaurus has the following components:
- Three content plugins:
plugin-content-pages. Plugins collect their content and emit JSON data. Plugin JS run in Node and use the
- Two theme plugins:
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.
A plugin is a function that takes two parameters
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
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.
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
Blog routing has several routes:
- Posts list:
/page/3… The component is
- Posts pages:
/2021/11/21/post1. It is customizable with
slugfront matter. The component is
- Tags list page:
/tags. The route is customizable through the
tagsBasePathoption. The component is
- Tag pages:
/tags/dotnet. It is customizable through the tag’s
permalinkfield. The component is
- Archive page:
/archive. It is customizable through the
archiveBasePathoption. The component is
Docs routing defeins nested routes. At the top, it registers version paths:
/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.
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.
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/themedirectory, 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
_ will be ignored and no routes will be created for that file.
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,
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:
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
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.