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.
Useful Links
- Markdown front matter: a list of fields that Docusaurus knows about and will do something with.