xinatcg/github-pages-docusaurus

A Docusaurus website deployed to GitHub Pages using GitHub Actions.

Deploy Docusaurus website to GitHub Pages using GitHub Actions

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