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.
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
BASE_URL
environment variableThe 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:
# 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