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..
- 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.
Docusaurus can be installed via npm. For a detailed explanation have a look at the official Docusaurus documentation.
Configurations are placed in
docusaurus.config.js at the root directory of your Docusaurus installation. For further explanations look at the official documentation.
See the official documentation.
Assets (images, gifs, videos, etc.) are stored inside the
static directory. Look at the usage chapter to see how to import them.
Video links from YouTube (optionally with preview) can be embedded using HTML.
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.
The main content of Docusaurus is written in Markdown files (
.mdx file format).
.mdx format is recommended, because it supports React.
For detailed description look into the usage chapter.
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 usage chapter.
.js files saved in every directory, where content pages in MarkdownX can occur. Namely in:
The TOC (
If you create a new page add its
id here. The structure of a nested TOC is also defined there.
Docusaurus can be enhanced with a search function. It is integrated in the
If other presets or plugins are used, additional steps may be needed for setting up a search function.
The default search function is offered by Algolia. The best way is to integrate the search function after Docusaurus is fully set up and went online.
This is because your URL need to be publicly available in order to apply the Algolia search function.
If you plan to use a more customized search (e. g. with your own index) look at the Docusaurus official documentation or the Algolia and DocSearch documentations. Algolia itself offers different options. One of them is free, if you have a non-profit documentation website and the website is publicly available (i. e. not behind a firewall). It is also recommended to have a fixed URL that does not change, otherwise you have to tell Algolia your new URL. Algolia needs the URL to crawl your website every 24 hours. The built index is then stored on the Algolia servers. For the free plan you must register your website for DocSearch provided by Algolia. After that it can take several days until Algolia has checked your website and sent you an e-mail with instructions on how to set up their search function. It is important to know that the instructions from the e-mail are general for clients and more complicated than it is necessary and useful(!) for Docusaurus.Do not follow all instructions from Algolia when using Docusaurus!It is mostly just necessary to insert a key and the index name in `docusaurus.config.js` and save those values (key and index name) as environment variables:
Do not insert another app id provided by Algolia if you are using the free plan from Algolia. Otherwise the search does not work because Algolia itself inserts the app id. There is no need for an app id with free plan.
Error messages are also displayed in the browser console of a production Docusaurus.
If you want to modify how Docusaurus displays the search results retrieved from the Algolia API you can change the
Algolia Search Code in React
For example if you want to display all pages with multiple hits just once in the search results, get an inspiration for that from GitHub.
Of course you can also modify other functions of the Algolia React code in Docusaurus.
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
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
The blog instance is still initialized in the classic preset.
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
See the official Docusaurus documentation.
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 the usage chapter.
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.
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.
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.
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.
- 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.
- Clone the repository containing the Docusaurus instance to your machine
- Install the requirements
- Change code, write documentation, or blog content
- Commit and push
You can locally run a Docusaurus instance on localhost on default port 3000:
To run the Docusaurus instance on localhost on port 3001 or another port number:
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:
Sometimes it is useful if you encounter errors, e.g., during the build process:
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
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/master/) in the configuration file,
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:
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.
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 detailed explanations see the testing chapter.