Website

This website is built using Docusaurus 2, a modern static website generator.

Installation

$ yarn

Local Development

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

Using SSH:

$ USE_SSH=true yarn deploy

Not using SSH:

$ GIT_USER=<Your GitHub username> yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Deploy Docusaurus website to GitHub Pages using GitHub Actions

(Method from: https://github.com/LayZeeDK/github-pages-docusaurus)

This repository is an example of deploying a Docusaurus website to GitHub Pages using GitHub Actions.

Configuring the GitHub repository

It uses the new GitHub Pages experience with GitHub Actions to deploy the website.

Enable this experience in GitHub.com -> Repository -> Settings -> Pages -> Build and deployment -> Source by selecting GitHub Actions instead of the legacy Deploy from a branch option.

In GitHub.com -> Repository -> Settings -> Environments you should see a GitHub Environment named github-pages.

Configuring Docusaurus

Generate a Docusuarus website using the following command:

yarn create docusaurus <folder-name> classic --typescript

Make the following changes to the docusaurus.config.js configuration file:

1. Create the constants organizationName and projectName

   const organizationName = "<github-organization-name>";
   const projectName = "<repository-name>";

2. Set the URL

   const config = {
     // (...)
     url: `https://${organizationName}.github.io`,
   };
   const baseUrl = /${projectName}/`;

3. Configure the base URL

   const config = {
     // (...)
     baseUrl: `/${projectName}/`,
   };

4. Set the organizationName and projectName options

   const organizationName = "<github-organization-name>";
   const projectName = "<repository-name>";
   
   const config = {
     // (...)
     organizationName,
     projectName,
   };

5. Configure the blog and docs edit URLs

   const config = {
     // (...)
     presets: [
       [
         "classic",
         /** @type {import('@docusaurus/preset-classic').Options} */
         ({
           // (...)
           docs: {
             // (...)
             editUrl: `https://github.com/${organizationName}/${projectName}/tree/main/`,
           },
           blog: {
             // (...)
             editUrl: `https://github.com/${organizationName}/${projectName}/tree/main/`,
           },
         }),
       ],
     ],
   };

Adding a GitHub Actions deployment workflow

Use a GitHub Actions workflow template for GitHub Pages from the actions/starter-workflows repository. Place it in .github/workflows/<workflow-name>.yml.

Add steps for building the website before the GitHub Pages actions are executed and specify the path to the actions/upload-pages-artifact:

# (...)
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      # 👇 Build steps
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16.x
          cache: yarn
      - name: Install dependencies
        run: yarn install --frozen-lockfile --non-interactive
      - name: Build
        run: yarn build
      # 👆 Build steps
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # 👇 Specify build output path
          path: build
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2