Docusaurus

Description

This plugins handles the organisation and generation of a Docusaurus site, regardless of the way source content is organized. The most important option is the structure which defines where to look for content and how to organize it in the final site.

The plugin provides sane defaults in order to generate a simple Docusaurus site hassle free, while also providing the flexibility to customize the site to your needs through options like static_assets and extra_files, the latter allowing you to overwrite complex customization files from Docusaurus.

In docs only mode, in order to customize the landing page you can either copy a intro.md file under the docs folder, using the extra_files option and the autogenerated sidebar, or you can add an entry in the structure option. In both cases, the file should have a frontmatter like this:

---
slug: /
---

Regardless of how you organize your files, Markdown links to files should still work after the Docusaurus structure is created, if you copied the files you are linking to. This is due to a step in the build process that looks for links and resolves them to the final destination.

A small level of familiarity with docusaurus is recommended in order to use this plugin.

Options

parameter	type	required	default	description
course_name	str	false	Course	The name of the course. This is reflected in the homepage of the resulting docusaurus site.
sidebar	str	false	auto	One of auto, js or custom. auto uses the docusaurus autogenerated sidebar; js will generate a sidebar.js file based on the structure parameter; custom will copy a sidebar.js file from the lcoation specified by sidebar_location
sidebar_location	str	false	$input_dir/sidebar.js	The location of the sidebar.js file to use if sidebar is set to custom.
sidebar_name	str	false	sidebar	Sidebar name to use inside the sidebar.js file.
docs_only	bool	false	true	Switch for the docusaurus docs only mode.
structure	see below (Structure section)	true	N\A	The structure of the course. This is used to generate the sidebar. Leaf nodes are identified by the presence of the location and name attributes.
static_assets	list[str]	false	[]	A list of static assets to copy to the static directory under the docusaurus build directory.
extra_files	list[str]	false	[]	A list of extra files to copy to the docusaurus build directory.
config_meta	Mapping[str, str]	false	N\A	The metadata to add to the docusaurus docusaurus.config.js file.
config_socials	Mapping[str, str]	false	N\A	The social media links to add to the docusaurus docusaurus.config.js file.
copyright_string	str	false	N\A	The copyright string to add to the docusaurus docusaurus.config.js file.
logo	str	false	N\A	The logo to use for the docusaurus site. If not specified, the default docusaurus logo will be used.
logo_dark	str	false	N\A	The dark logo to use for the docusaurus site. If not specified, the default docusaurus logo will be used.
debug	bool	false	false	Whether to keep the docusaurus build directory alongside the built output.
math	bool	false	false	Whether math equation support should be included in the build.

Example:

docusaurus:
  plugin: docusaurus
  options:
    course_name: Example Course
    logo: path/to/logo.svg
    logo_dark: path/to/logo_dark.svg
    docs_only: false
    sidebar: js
    sidebar_name: example_sidebar
    structure:
      - Lecture:
          path: /build/embed_reveal
          subsections:
            - Compute: Compute/Compute.mdx
            - Data: Data/Data.mdx
      - Lab:
        - Compute:
            path: content/chapters/compute/lab/content
            extra:
              - ../media
              - ../quiz
            subsections:
              - Overview: overview.md
              - Benchmarks: benchmarks.md
              - Processes: processes.md
    static_assets:
      - Compute: /path/to/content/chapters/compute/lecture/_site
      - Data: /path/to/content/chapters/data/lecture/_site
    extra_files:
      - index.js: src/index.js
    config_meta:
      title: Example Course
      url: http://localhost/
      baseUrl: /
      onBrokenLinks: warn
      onBrokenMarkdownLinks: warn
    config_socials:
      Main site: https://example.com
    copyright_string: Example Course Team
    debug: false

Note that this is a complex example. Usually, most of the parameters can be ommited, relying on the default values.

Structure

The structure option is complex and will be explained with examples in this section.

For the examples below we have the folowing directory structure in our repository:

content
└── chapters
    └── compute
        └── lab
            ├── content
            │   ├── benchmarks.md
            │   ├── overview.md
            │   └── processes.md
            ├── media
            │   ├── pic1.jpeg
            │   ├── pic2.svg
            │   ├── pic3.svg
            │   ├── pic4.svg
            │   └── pic5.svg
            ├── quiz
            │   ├── quiz1.md
            │   ├── quiz2.md
            │   └── quiz3.md
            └── solution
                └── stuff-we-do-not-need-here

We want to turn this into the following sidebar in docusaurus:

Labs
└── Compute
    ├── Overview
    ├── Benchmarks
    └── Processes

The directory structure under docusaurus will look like this:

docs
└── Labs
    └── Compute
        ├── media
        ├── quiz
        ├── overview.md
        ├── processes.md
        └── benchmarks.md

At its core, the structure option is just a list of sidebar elements. Categories/chapters are identified by the presence of children, via the subsections key, or by simply specifying the subchapters as a list. The following 2 examples are equivalent in meaning.

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          subsections:
            - Overview: overview.md
            - Benchmarks: benchmarks.md
            - Processes: processes.md

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          - Overview: overview.md
          - Benchmarks: benchmarks.md
          - Processes: processes.md

Using the first option, while longer, is necessary when you want to specify extra files to copy in the directory of a chapter/section (the extra option), or when you use the path option (more below).

In the example above, - Overview: overview.md represents a content page that will be rendered by docusaurus. The path of overview.md is relative to the root of the repository unless otherwise specified.

If your documents have a folder-like structure (like the one at the begging of the section), you need to specify the full path, as seen in this example:

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          subsections:
            - Overview: content/chapters/compute/lab/content/overview.md
            - Benchmarks: content/chapters/compute/lab/content/benchmarks.md
            - Processes: content/chapters/compute/lab/content/processes.md

In order to avoid this kind of repetition that makes it hard to read the config file, the path option can be used on any subsection to group a common set of files.

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          path: content/chapters/compute/lab/content
          subsections:
            - Overview: overview.md
            - Benchmarks: benchmarks.md
            - Processes: processes.md

The path you specify in the path option will be prepended to any of the values that represent paths under this section. You can also specify more path options down the line and they will be glued together.

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          path: path1
          subsections:
            - More Content:
                path: path2
                subsections:
                  - Overview: overview.md

In the example above, the path to the Overview page will be path1/path2/overview.md.

For media and other files you might include in your documents, you can use the extra key to copy them in the folder of a section, like so:

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          path: content/chapters/compute/lab/content
          extra:
            - ../media
            - ../quiz
          subsections:
            - Overview: overview.md
            - Benchmarks: benchmarks.md
            - Processes: processes.md

Note that this is also affected by the path variable, the original location of the media directory being content/chapters/compute/lab/media, hence the .., representing the parent directory.

Leaf nodes (rendered pages based on your content) will always have the form k: v, where v is a string. These have a few particularities.

The key (k) is, most of the time just a string representing the title of a sidebar element. It can also take the following forms:

• Title/index_file_without_extension
• Title/ (default index file will be README.md)

The value (v) is, most of the time a string, representing the path to the file that will be rendered. It can also be the path to a directory with multiple files. In this case, k needs to have one of the two forms above to specify which file will be rendered. Rewriting our example using this syntax looks like this:

docusaurus:
  plugin: docusaurus
  options:
    structure:
      - Compute:
          path: content/chapters/compute/lab
          extra:
            - media
            - quiz
          subsections:
            - Overview/overview.md: content/
            - Benchmarks/benchmarks.md: content/
            - Processes/processes.md: content/

This will also generate a different docusaurus structure:

docs
└── Labs
    └── Compute
        ├── media
        ├── quiz
        ├── Overview
        │   └── overview.md
        ├── Processes
        │   └── processes.md
        └── Benchmarks
            └── benchmarks.md

Because of the special syntax for k, if you want to use / in the name of a section, you will need to URL encode it, using %2F instead.