Installation

Enabling GitHub Pages

In your repository on GitHub, go to Settings → Pages. Under Build and deployment → Source, change the option to GitHub Actions.

Creating a GitHub Workflow

In your project, create a GitHub Workflow file:

# .github/workflows/github-pages.yml
name: GitHub Pages

on:
  workflow_dispatch: {}
  push:
    branches: ['main']
    tags: ['*']

jobs:
  upload-docs:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    env:
      DOCS_DIR: 'docs/'
      OUTPUT_DIR: '_site/'
      MAIN_BRANCH: 'main'
    steps:
      - name: Configure pages
        uses: actions/configure-pages@v5
        id: configure-pages
      - name: Checkout
        uses: actions/checkout@v3
        with:
          ref: ${{ env.MAIN_BRANCH }}
          fetch-depth: 0 # checkout a non-shallow copy so the generator can generate docs for all major versions
      - uses: gopxl/docs@main
        with:
          site-url: ${{ steps.configure-pages.outputs.base_url }}
          docs-directory: ${{ env.DOCS_DIR }}
          output-directory: ${{ env.OUTPUT_DIR }}
          main-branch: ${{ env.MAIN_BRANCH }}
      - name: Upload pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ env.OUTPUT_DIR }}
      - name: Deploy pages
        uses: actions/deploy-pages@v4

Linking the site from the GitHub repository

Optionally, it's possible to configure the GitHub Pages site as website of the GitHub repository. This way, it will be linked in the About section. To do this, click on the cog icon in the top-right corner in the About section:

The About section on a GitHub repository index page

This will open a dialog where a website can be configured. Enable "Use your GitHub Pages website" and click on "Save changes" and you're good to go.

The edit repository details dialog

The GitHub Pages link will be displayed below the description:

The About section on a GitHub repository index page

Viewing your website

It is also possible to determine the website URL using the repository URL. If your GitHub repository is hosted at https://github.com/owner/project, your GitHub Pages site will be available at https://owner.github.io/project.