Docs: display documentation with docusaurus

.github/maintainers_guide.md

@@ -19,30 +19,11 @@ Test code should be written in syntax that runs on the oldest supported Node.js
 
 A useful trick for debugging inside tests is to use the Chrome Debugging Protocol feature of Node.js to set breakpoints and interactively debug. In order to do this you must run mocha directly. This means that you should have already linted the source (`npm run lint`), manually. You then run the tests using the following command: `./node_modules/.bin/mocha test/{test-name}.js --debug-brk --inspect` (replace {test-name} with an actual test file).
 
-### Generating Documentation
+### Managing Documentation
 
-The documentation is built using [Jekyll](https://jekyllrb.com/) and hosted with GitHub Pages.
-The source files are contained in the `docs` directory. They are broken up into the `_basic`, `_advanced`, and `_tutorials` directories depending on content's nature.
+See the [`/docs/README.md`](./docs/README.md) file for documentation instructions. 
 
-All documentation contains [front matter](https://jekyllrb.com/docs/front-matter/) that indicates the section's title, slug (for header), respective language, and if it's not a tutorial it contains the order it should appear within its respective section (basic or advanced).
-
-To build the docs locally, you must have [Ruby](https://www.ruby-lang.org/en/) installed. To easily install and manage different Ruby versions, you can use [`rbenv`](https://github.com/rbenv/rbenv). If you use macOS, you can install it via `brew install rbenv`. Hook it up to your shell by running `rbenv init` and following the instructions. Finally, install the required version for building the docs (this version is stored in the `.ruby-version` file) via `rbenv install <version>`.
-
-To build the docs, navigate to the `docs` folder and run `bundle install` to install necessary gems (Ruby dependencies). Run `bundle exec jekyll serve` to start up a local server which will compile documentation source and serve its contents.
-
-_(zsh users)_: If you are running into issues with permissions to install ruby gems during `bundle install`, you may need to add `eval "$(rbenv init - zsh)"` to your ~/.zshrc then run `source ~/.zshrc`. 
-
-#### Adding beta documentation
-When documentation is in a beta state, it requires a new, distinct collection of docs. The process is a little nuanced, so make sure to build the documentation locally to make sure it appears how you expect. To create a new collection:
-1. Add content
-* Add a new folder to docs with an underscore (ex: `_steps`).
-* Add documentation sections to that folder, with similar front matter to the `_advanced` and `_basic` sections.
-* Add an overview section that explains the beta state of the category. This should always be `order: 1` in the front matter.
-
-2. Configure layout
-* Update `docs`>`_config.yml` with the new collection you created under `collections` (the same as the folder name - ex: `steps`). While you're there, add the sidebar title under `t`.
-* In `docs`>`_layouts`>`default.html` make a copy of the `basic` or `advanced` section, and modify the div ID and content to correspond to your beta collection. This step requires you to use variables from `_config.yml`.
-* Now in `docs`>`_includes`>`sidebar.html`, create a new section after the basic and advanced sections. Again, copy the `basic` or `advanced` section to use as a template. Be careful with the variable naming—it's a little more complex than in `default.html`, and requires you to use variables from `_config.yml`.
+If you're not touching the `/docs` folder, you don't need to worry about the docs setup affecting your PR.
 
 ### Releases
 _For beta releases, see Beta Releases section below:_

.github/workflows/docs-deploy.yml

@@ -0,0 +1,62 @@
+name: Deploy to GitHub Pages
+
+on:
+ pull_request:
+ branches:
+ - main
+ paths:
+ - 'docs/**'
+ push:
+ branches:
+ - main
+ paths:
+ - 'docs/**'
+ workflow_dispatch:
+
+jobs:
+ build:
+ name: Build Docusaurus
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: npm
+ cache-dependency-path: docs/package-lock.json
+
+ - name: Install dependencies
+ run: npm ci
+ working-directory: ./docs
+
+ - name: Build website
+ run: npm run build
+ working-directory: ./docs
+
+ - name: Upload Build Artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./docs/build
+
+ deploy:
+ name: Deploy to GitHub Pages
+ if: github.event_name != 'pull_request'
+ needs: build
+
+ # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+ permissions:
+ pages: write # to deploy to Pages
+ id-token: write # verifies deployment is from an appropriate source
+
+ # Deploy to the github-pages environment
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ runs-on: ubuntu-latest
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4

docs/.gitignore

@@ -1,7 +1,5 @@
-_site
-Gemfile.lock
-.env
-.jekyll-metadata
-.vscode/
-.bundle/
-vendor/
+node_modules/
+.docusaurus
+.DS_Store
+build/
+.stylelintrc.json