Skip to main content

Set Up Docusaurus

info

This page contains general information how to set up a Docusaurus instance everywhere. It follows the workflow used at KIT using Linux (Ubuntu), GitHub and npm, but the principles can also be adapted to other hosts and 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 then be installed via npm. For detailed explanation have a look at the official Docusaurus Documentation.

Configuration File#

All important 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.

Structure#

Assets#

Assets (images, gifs, videos, files in general) are typically stored inside the static directory. Look at the usage chapter to see how to import them. Video links from YouTube can also be embedded with HTML with a provided preview etc.

CSS#

Custom CSS (also for SCSS) can be placed in src/css and must be named in the configuration file. The CSS is then automatically imported in 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 stored in Markdown files. There are .md or .mdx file endings possible. .mdx is recommended, because it also supports the usage of 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 informations can be found in the Docusaurus documentation about assets and versioning and 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, that must contain every single page, that should be visible. If you create a new page, add its slug or id here. The structure of a nested TOC is also defined here.

Search bar#

Set Up#

Additionally there can be a search function added to docusaurus. It is integrated in the @docusaurus/preset-classic. If another preset or plugins are used, there may be additionally steps needed for setting up a search function. The default search function is offered by Algolia and that is probably the easiest way to add a search function. The best way is to integrate the search function after Docusaurus is fully set up and went online, because you need a public available URL to apply for the Algolia search function.

If you plan to use a more customized search (e. g. with your own index) than look at the Docusaurus official documentation or the Algolia and DocSearch documentations. Algolia itself offers different options to use it. One of them is totally 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 do 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 could take several days until Algolia has checked your website and sent you an e-mail with instructions 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 the inserted 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 configurating their products: Algolia Sign Up. But 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 possibilities 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 do not throw errors:

// 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 disṕlayed in the Browser console of an 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 creating the directories and adding the code into it src/theme/SearchBar and src/theme/SearchPage. For example if you want to display every pages with multiple hits just once in the search results then 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, define the layout and offer functionalities like the search bar. More information about presets. The default preset is the classic one. A preset maintains one docs and one blog instance. If you want to serve multiple docs instance, e. g. for versioning you need to replace this property in the preset with multiple plugins in the configuration file.

For example you want to install two versions of the documentation for manual A, one for version 0.8 the other for version 0.9, then 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 also 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 more the layout than the underlying structure. For more options look in 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 safed in a .env file or stored as secrets in GitHub or GitLab. The last 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 is usually not shared via a 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 of 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 needed to install or clone Docusaurus locally and install the necessary things from the requirements. There are to possible ways: either your are the creator and maybe admin of an Docusaurus instance or you are a developer contributer to an existing Docusaurus instance.

creator (or admin) of an Docusaurus instance#

If you are a creator than you have probably the task to set up a new Docusaurus instance. A common workflow could be this:

  • Install Docusaurus locally on your developer machine: See the installation chapter.
  • Configure and develop the Docusaurus instance
  • Create a repository of your favorite VCS
  • Push the whole locally developed Docusaurus instance to your VCS. It is very important to push the whole code of the instance because then other developers can easily clone the code and it is also helpful for deployment.
    Normally hidden files, node, yarn or Docusaurus packages, build directories and maybe additional files are in the .gitignore (or corresponding configurations for other VCSs), 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.

developer of an Docusaurus instance#

If you are a normal developer than probably a creator or an admin has already set up Docusaurus and pushed to a VCS. A common workflow could be this:

  • Clone a repository that contains a Docusaurus instance to your local developer machine
  • Maybe it is necessary to install the requirements
  • Run npm install or yarn install
  • Change code or write documentation or blog content
  • Commit and push

develop and run#

To check your local development for your Docusaurus instance you can use common npm commands.
To run a Docusaurus instance on localhost on default port 3000:

npm start

To run Docusaurus instance on localhost on port 3001 or another port number, if 3000 is already in use:

npm start -- --port 3001

Check if your Docusaurus instance could be build correctly. That command is also helpful before you push code to solve errors and a hint if your links are solved correctly:

npm run build

clear cache#

Sometimes useful if you encouter errors, e. g. during 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 of your docusaurus site. Another solution is to look into the .docusaurus folder. For debugging the JSX code you can use the normal Browser console or other debugger for JavaScript/React.

Contribution to online version via Verison Control System#

Every documentation page can be edited online without deeper knowledge of Docusaurus via an Edit this page button. To enable this, insert a link for editions 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 easily 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 documenation 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 Continious Deployment via SSH can be found on GitHub. For detailed explanations see the testing chapter.

Common Errors#

Last updated on by maipy