Deploying to GitHub Pages

GitHub Pages^[1] allows you to host your project in a folder, which is your repositories name, for example:
https://owner.github.io/repository_name
To get setup with GitHub Pages, ensure that your repository is hosted in GitHub and you are in the root of the Git repository.

🛠 In the root of your git repository run myst init --gh-pages

The command will ask you questions about which branch to deploy from (e.g. main) and the name of the GitHub Action (e.g. deploy.yml). It will then create a GitHub Action^[2] that will run next time you push your code to the main branch you specified.

The command myst init --gh-pages will guide you through deploying to GitHub Pages. — The command `myst init --gh-pages` will guide you through deploying to GitHub Pages.

Navigate to your repository settings, click on Pages and enable GitHub pages. When choosing the source, use GitHub Actions:

🛠 Turn on GitHub Pages using GitHub Actions as the source.

To trigger action, push your code with the workflow to main.

BASE_URL environment variable

The build and site assets are in the /build folder, which would point outside of the current repository to a repository called ‘build’, which probably doesn’t exist!

To fix this, we can change the base url that the site is mounted to, which can be done through the BASE_URL environment variable:

export BASE_URL="/repository_name"

The base URL is absolute and should not end with a trailing slash. This can be done automatically in a GitHub Action by looking to the github.event.repository.name variable.

Full GitHub Action

The GitHub Action to build and deploy your site automatically is:

deploy.yml

# This file was created automatically with `myst init --gh-pages` 🪄 💚

name: MyST GitHub Pages Deploy
on:
  push:
    # Runs on pushes targeting the default branch
    branches: [main]
env:
  # `BASE_URL` determines the website is served from, including CSS & JS assets
  # You may need to change this to `BASE_URL: ''`
  BASE_URL: /${{ github.event.repository.name }}

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: 'pages'
  cancel-in-progress: false
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 18.x
      - name: Install MyST Markdown
        run: npm install -g mystmd
      - name: Build HTML Assets
        run: myst build --html
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: './_build/html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Footnotes¶

To learn more about GitHub Pages, see the GitHub documentation
↩
To learn more about GitHub Actions, see the GitHub documentation. These are YAML files created in the .github/workflows folder in the root of your repository.
↩