It's been a rough few months since I last wrote anything. I normally did most of my work in C# with .Net, but at the end of October that changed. I've been through a crash course on React.js and the following death march. Then I finally came down with covid (managed to dodge it for most of the pandemic). But with all that, when I finally got back to updating the documentation for NuGetDefense, I wanted to be able to leverage my new familiarity with React while keeping the docs themselves simple enough that anyone could contribute. With that in mind, I found Docusaurus.
What Is Docusaurus?
Docusaurus is a framework for React.js that focuses on MarkDown. This means all the documentation is as easy to edit as a text file. Docusaurus doesn't even require React.knowledge to use. Settings are made in a well documented docusaurus.config.js file (which ends up being mostly JSON) and all the doc entries are .md or .mdx (the markdown equivalent of JSX) files.
Why Not Just Build A Doc Site With React?
I originally started with Blazor. I loved it, but .Net Core 3.1 it was too slow when used as a static site on GitHub. I switched to Gatsby because it has a lot of nice features and a good plugin system. But trying to write a doc website in 10 minute bursts was not great (and getting packages up to date was a hassle).
I completely configured, and deployed docusaurus in an hour initially. I'm not using any of the more advanced features, but that makes contributions to the base documents more approachable while still letting me handle routing, the home page, etc however I feel. It does support items like "Versioned Documentation", a built in Blog for the project, etc. But even the basic features include Dark Mode, a Basic Themes, Code Highlighting via prism.js, and of course a menu with Table of Contents.
Geting Started
I like to use Yarn and Typescript, so I'll cover that here. The rest is mostly editing the markdown files and switching out images for your project.
Setting Up Yarn
Yarn's official documentation indicates the preferred method now to use Corepack. As of this writing Corepack is documented as experimental though. So you may choose not to use (shouldn't be difficult to switch later). I am assuming you have Node installed. If not, you can grab it from nodejs.org.
Without Corepack:
If you've never used Yarn before on this machine, youll need to install it globally first with:
npm install yarn -g
Next we need to setup the project's yarn:
yarn set version berry
You can run yarn set version stable to update this, but without running the first command, it will only install the latest version of Yarn Classic.
With Corepack:
Dependant on your version of Node, you may need to install Corepack:
Node.js 16.10 and above:
corepack enable
Node.js 16.9 and below:
npm install corepack -g
Setting up Docusaurus
Docusaurus has a CLI setup tool that takes care of getting you started:
npx create-docusaurus@latest my-website classic --typescript
The important bit there is --typescript. Without that, you'll have to manually change any configurations or be stuck using javascript.
The run:
yarn add --dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
Finally, the official docs say to add an "extends" to your tsconfig , but in my case it was added automatically so you can probably just double check the tsconfig for:
"extends": "@tsconfig/docusaurus/tsconfig.json"
Don't Use Typescript for Configuration
Docusaurus and many other tools do not support using Typescript for your config files. You can transpile them yourself, but usually config files don't gain enough from Typescript usage to be worth adding an extra build step.
Rebranding
You probably don't want a website with docusaurus branding all over the place. There are a few key files and configs to change to match the project it covers.
Images
These are the main three images used for branding. GIMP - GNU Image Manipulation Program can be used to generate them if you have a base image to start with.
static/img/logo.svgstatic/img/docusaurus.pngstatic/img/favicon.ico
Settings
Settings as a whole are likely to evolve more as the project does, but there are a few to look for. All of these are found in the docusaurus.config.js file in the root of the project.
- GitHub links: there are a few by default
- Edit URL's: most of these link back to Docusaurus or FaceBook repos
- Titles: A find/replace for Docusaurus will make finding these pretty easy
Deploy And Enjoy
When you get ready to deploy:
yarn build
after it finishes, the build folder is everything your static site needs to run.