Skip to main content

Set Up Docusaurus

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 the usage 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 the usage 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 usage 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.

Search bar#

Set Up#

Docusaurus can be enhanced with a search function. It is integrated in the @docusaurus/preset-classic. 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:
module.exports = {
// ...
themeConfig: {
// ...
algolia: {
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
},
},
};
Warning

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.

Algolia also provides the ability to create an account for accessing statistics and configuring their products: Algolia Sign Up. If you are using a free plan it is not necessary to use an account because you are very limited in configurations and your configuration options are on the Docusaurus site. If you encounter problems with your search you can directly access the Algolia API written in different programming languages or write the Algolia customer service. Here are small snippets in JavaScript and Python to check if your search works:

// npm install algoliasearch
import algoliasearch from 'algoliasearch';
const client = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY');
console.log(client);
# pip install --upgrade 'algoliasearch>=2.0,<3.0'
from algoliasearch.search_client import SearchClient
client = SearchClient.create('YOUR_APP_ID', 'YOUR_API_KEY');
index = client.init_index('YOUR_INDEX_NAME');
index.search('YOUR_SEARCH_WORD');

Error messages are also displayed in the browser console of a production Docusaurus.

Advanced: configure display of search results etc.#

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 by populating src/theme/SearchBar and src/theme/SearchPage directories. 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, 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 the usage 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/master/) 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 detailed explanations see the testing chapter.

Last updated on by Jan C. Brammer