Port rojo.space from MkDocs to Docusaurus

[unix-system]

TL;DR

Docusaurus is a well known Facebook created documentation and blog site that is used to help rapid development of internal Facebook projects. It has a number of maturing features that make it attractive to us:

• Versioning so we can display different documentation for each version, including whether that version is supported by us or not)
• Built on React, as is our current SSG site (currently on Gatsby.js which means we don't have to rewrite our homepage to unify the site)
• Has a Built-in Blog Plugin which looks really nice
• Looks great out of the box (and includes Dark Mode 🌙)

Want to check out the built Rojo docs in Docusaurus? Check it out here: https://unix-system.github.io/rojo.space/ 😄 You can also download it locally and run yarn then yarn start to preview a local copy.

Rationale

Our current documentation has some issues - some of these are content based, but much of this is due to our use of MkDocs. MkDocs is a well known Python-based content generator for technical documentation. It is easy to setup and has a mature ecosystem. However, we have some problems:

• Bad support for static pages, so we must use a heavy library (Gatsby.js) to render our homepage
• Requires a Python build process which means we must use both Python (build MkDocs) and NodeJS (our React content).
• Doesn't support versioning so we've had to come up with a non-intuitive solution for displaying versioned content
• Unless we put a lot of effort into theming, the Material theme doesn't match our main site at all

All of these issues are fixed by moving over to Docusaurus. I've done the preparatory work on this and have not made any content changes to the sites.

Here is a summary of the changes I have made:

1. Removed all legacy artefacts (such as MkDocs, Python)
2. Restructured the versioned files to be under the Docusaurus-compliant versioned_docs folder with clones of the relevant files
3. Moved appropriate relative images over to absolute images (This isn't ideal - we should move the legacy images over to their respective relative folders, but this had issues at the time)
4. Removed the MkDocs TOC header and replaced with a custom Title for each document
5. Removed the bin folder and moved its content
   • I have not moved over the diagram build script at this moment, however all diagrams are present. In future, we should set up a NodeJS based diagram builder that can be run locally via yarn
6. Moved over our TOC to sidebars.js and versioned_sidebars files where appropriate
7. Fixed formatting errors (namely centered image css macros) where appropriate
8. Added placeholder for the Blog

Dependencies

Some new build dependencies are going to be used; I will only include top-level dependencies:

• actions/checkout@v1
• actions/setup-node@v1
• webfactory/ssh-agent@v0.5.0 - Creates the SSH agent to deploy to GitHub Pages. Required.

Vulnerability Scan & Security

Vulnerability Scan HTML: snyk-scan.zip

Package / Supply Chain Vulnerabilities I have scanned all available NPM packages using Snyk and some potential vulnerabilities were discovered; I decided to upgrade Docusaurus to fix a websocket related vulnerability. Due to the serverless nature of this site, I have decided to accept the residual risk of any residual vulnerabilities as there is no patch available (at the moment) and they have not been shown to be exploitable:

• Risk Appetite: Cautious (? assumed)
• Risk Probability: Low 🟢
• Risk Impact: Low 🟢
• Risk Treatment: Accept 🟢 (since the residual and pre-treatment risk ratings are identical there is no need for treatment)

SSH usage We are using SSH, which can be an inherently dangerous option for communication. Whilst it is very unlikely that SSH keys could be used to compromise GitHub, special attention should be put on using Deploy Keys rather than personal SSH keys to deploy otherwise the impact scope of a compromised key would broaden to, depending on user privileges, the rest of the rojo-rbx organisation.

• Risk Appetite: Cautious (? assumed)
• Risk Probability: Low 🟢
• Risk Impact: High 🔴
• Risk Treatment: Control 🔵 - Limit scope of SSH key deployments to only the rojo.space project

Deployment Steps

The PR branch has been configured correctly to work with the https://rojo.space domain out of the box. The only input is the SSH Secret that should be created as defined above as a Deploy Key for this repository and entered into Secrets as GH_PAGES_DEPLOY

Hope this makes sense to everyone and I look forward to your comments!

[unix-system]

@LPGhatguy Heya, would I be able to get a review on this?

[LPGhatguy]

Hey, I tried to give this PR a shot.

Just running start on a fresh checkout gives you...

$ npm start

> rojo.space@0.1.0 start C:\Users\lucien\projects\rojo.space
> docusaurus start

'docusaurus' is not recognized as an internal or external command,
operable program or batch file.

I tried running docusaurus directly using npx like the Docusaurus docs mention and I get...

$ npx docusaurus --version
  √ gifsicle pre-build test passed successfully
  √ jpegtran pre-build test passed successfully
  √ optipng pre-build test passed successfully
Error: No siteConfig.js file found in website folder!

I'm going to try moving the content here into a fresh Docusaurus project and see how that goes.

[LPGhatguy]

Thank you so much for the contribution here! I ended up taking most of the configuration and continuing it in #49. It ended up being easier to scaffold a new Docusaurus project and transplant the content into it.

I also ended up setting up redirects, offline search, and a bunch of new documentation content.

The first blog post on the new website will be crediting you for setting this up. Thank you again, and I'm glad we went down this road!