Skip to main content

Docusarus

Docusarus is the engine that generates this wiki. I picked this system based on its use by Nikita Voloboev in their knowledgebase.

Dev Serverโ€‹

Run npm start to start the dev server. This runs docusaurus start, which is running webpack-dev-server under the covers (although I donโ€™t think webpack config files can be passed in).

My local install is configured to run on port 3001 to avoid conflicts with the default Ruby On Rails port.

Folder Categorizationโ€‹

Categories can be customized by creating a _category_.json in a directory1.

Automatic Deployments to Github Pagesโ€‹

Docusaurus has automatic build and deploy wrapped into a single command:

npm run deploy

This works great for local deploys, but requires some additional commands to work with Github Actions.

The current build and deploy action can be found on Github, but in short, the approach is:

  • Check out the code
  • npm ci
  • Configure git credentials
  • Run npm run deploy
  • Cleanup (done automatically)

Custom Javascript Loadingโ€‹

Custom Javascript is loaded via docusaurus.config.js in the scripts section2:

const config = {
scripts: [
// String style
"my-js-host.example.com/my.js",
// Object style
{
src: "my-js-host.example.com/my.js",
defer: true,
},
],
};

Syntax Highlightingโ€‹

Syntax highlighting is handled by Prism. Additional languages need to be imported into docusaurus.config.js.

Known Issuesโ€‹

  • When writing new articles, linking an article to that new article requires a restart of the local server (npm start) in order to pick up that new articleโ€™s link.

Footnotesโ€‹

  1. https://docusaurus.io/docs/sidebar/autogenerated#category-index-convention โ†ฉ

  2. https://docusaurus.io/docs/api/docusaurus-config#scripts โ†ฉ