Skip to content

FairyProject/docs

 
 

Repository files navigation

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

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 47.9%
  • TypeScript 31.5%
  • CSS 16.1%
  • MDX 4.5%