Maintaining

info

This page contains general information on how to set up a Docusaurus instance anywhere. It follows the workflow used at KIT using Linux (Ubuntu), GitHub, and npm, but the principles can be adapted to other hosts, OS, etc..

Installation Process

Requirements

• Install NodeJS
• Install npm or yarn
• On Linux, macOS or WSL: Install NVM to install Node and npm. If you prefer yarn over npm, you can install yarn through npm, if you have npm already installed.

Installation

Docusaurus can be installed via npm. For a detailed explanation have a look at the official Docusaurus documentation.

Configuration File

Configurations are placed in docusaurus.config.js at the root directory of your Docusaurus installation. For further explanations look at the official documentation.

Update

See the official documentation.

File structure

Assets

Assets (images, gifs, videos, etc.) are stored inside the static directory. Look at This Documentation chapter to see how to import them. Video links from YouTube (optionally with preview) can be embedded using HTML.

CSS

Custom CSS and SCSS is placed in src/css and must be named in the configuration file. The CSS is then automatically imported on every content page.

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs:false,
        blog: {
          showReadingTime: true
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ]

Markdown

The main content of Docusaurus is written in Markdown files (.md or .mdx file format). The .mdx format is recommended, because it supports React. For detailed description look into This Documentation chapter.

Paths

Setting paths can get complicated when you are deploying your website under another directory on the server or if you are using versioning. Detailed information can be found in the Docusaurus documentation about assets and versioning as well as in the this Documentation chapter.

React/JavaScript

React is the main frontend framework in Docusaurus. Beside React components in MarkdownX you can create your own React or pure JavaScript snippets in .js files saved in every directory, where content pages in MarkdownX can occur. Namely in:

• docs
• blog
• src/pages

Table of contents

The TOC (sidebars.js) is a JavaScript module. It must contain every single page that you wish to be visible. If you create a new page add its slug or id here. The structure of a nested TOC is also defined there.

Presets, Plugins and Themes

Presets are a bundle of themes and plugins that define the layout and offer functionalities like the search bar. Find more information about presets here. The default preset maintains one docs and one blog instance. If you want to serve multiple docs instances, e.g., for versioning you need to replace this property in the preset with multiple plugins in the configuration file.

For example, if you want to install two versions of the documentation for manual A, one for version 0.8 the other for version 0.9, set docs:false in the preset property and add a property @docusaurus/plugin-content-docs under the plugins property on the level of the preset. If you want to serve another manual B in the same docusaurus instance, you need to add a second property @docusaurus/plugin-content-docs. The blog instance is still initialized in the classic preset.

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs:false,
        blog: {
          showReadingTime: true
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ]

plugins: [
      "@docusaurus/plugin-content-docs",
    {
      id: "A",
      showLastUpdateTime: true,
      showLastUpdateAuthor: true,
      editUrl:'...',
      sidebarPath: require.resolve('./sidebarsA.js'),
      path: "docs/A",
      routeBasePath: "docs/A",
      lastVersion: "current",
        versions: {
          current: {
            label: 'A 0.9',
          },
          '0.8': {
            label: 'A 0.8',
            path: 'version-0.8',
          },
        }
      }
  ]
  ,
  [
    "@docusaurus/plugin-content-docs",
    {
      id: "B",
      showLastUpdateTime: true,
      showLastUpdateAuthor: true,
      editUrl:'...',
      sidebarPath: require.resolve('./sidebarsB.js'),
      path: "docs/B",
      routeBasePath: "/docs/B",
    },
  ],
}

Themes are an addition to presets and plugins, but define the layout rather than the underlying structure. For more options visit the official Docusaurus Documentation. You can also create your own themes under src/theme.

Layout

See the official Docusaurus documentation.

Versioning

For adding multiple versions of one documentation to Docusaurus look at the plugin chapter to see how it is configured in the configuration file. To know how to install it look at the example in This Documentation chapter.

Version Control System (e. g. GitHub)

The Docusaurus instance can be saved in a VCS to enable development by multiple people. A VCS is also needed to enable online editing and online Continuous Integration/Deployment. Docusaurus supports the usage of the dotenv npm package. For that, import it in the configuration file. Environment variables are typically used there.

require('dotenv').config()
module.exports = {
  ...
}

Environment variables can be saved in a .env file or stored as secrets in GitHub or GitLab. The latter option is also useful for Continuous Deployment. If Docusaurus is developed locally in addition to Continuous Deployment on GitHub or GitLab, it is necessary that every developer has access to the .env file, which should not be shared on the VCS. For that, save it in another place or create dummy environment variables.

Development

There are two main ways to contribute to Docusaurus instance: either develop within a local Docusaurus installation or change the content of an online Docusaurus website via Version Control System (e. g. GitHub or GitLab). One of the important features of Docusaurus is the ability to edit a Documentation page via a VCS without the need for a locally installed Docusaurus and advanced programming knowledge.

Local installation

The Docusaurus development is based on npm. To change the configurations or script some JSX it is necessary to install Docusaurus and the requirements. There are two scenarios: 1. you are the creator and maybe admin of an Docusaurus instance, or 2. you are contributing to an existing Docusaurus instance.

creator (or admin) of a Docusaurus instance

• Install Docusaurus locally: See the installation chapter.
• Configure and develop the Docusaurus instance
• Create a repository on your favorite VCS
• Push the locally developed Docusaurus instance to your VCS. Normally hidden files, node, yarn or Docusaurus packages, build directories and maybe additional files are in the .gitignore, so they will not be pushed. But they can also be created easily locally or for deployment and it is also not useful to share them.

contributor to a running Docusaurus instance

• Clone the repository containing the Docusaurus instance to your machine
• Install the requirements
• Run npm install or yarn install
• Change code, write documentation, or blog content
• Commit and push

develop and run

You can locally run a Docusaurus instance on localhost on default port 3000:

npm start

To run the Docusaurus instance on localhost on port 3001 or another port number:

npm start -- --port 3001

Check if your Docusaurus instance could be build correctly. This command is also helpful before you push code in order solve errors and detect incorrectly resolved links:

npm run build

clear cache

Sometimes it is useful if you encounter errors, e.g., during the build process:

npm run clear

debug

Because Docusaurus is a high level framework, there is no dedicated way of live debugging. You can use the debug plugin to get some static information on your docusaurus site. Another solution is to look into the .docusaurus folder. For debugging the JSX code you can use the browser console or other debuggers for JavaScript/React.

Contribution to online version via Version Control System

Every documentation page can be edited online via the Edit this page button. To enable this, insert a link for editing in your VCS (e. g. https://github.com/ComPlat/chemotion_saurus/edit/main/) in the configuration file, usually under presets/docs/editUrl or plugins/<instance>/editUrl.

Deployment

A static Docusaurus website can be build with a npm or yarn command and then only this build directory needs to be pushed to a server:

npm run build --if-present

Recommendation

If you are serving your Docusaurus website under another directory than the default / you may encounter problems with paths for assets (images, files etc.). Look in the Docusaurus documentation for solutions: https://docusaurus.io/docs/static-assets.

Via GitHub Actions

Docusaurus can be fully built and deployed via GitHub or GitLab. For that a workflow file in yml is needed, where the current code is checked out (e. g. on every push), build via npm or yarn and the so created build directory pushed to a server via SSH. An example workflow for Continuous Deployment via SSH can be found on GitHub. For details have a look at the chapter on continuous integration.