Deploying your MyST Site

The default themes for MyST sites are applications that render structured data dynamically, and are not static HTML sites. This choice allows the websites to include many performance enhancements such as pre-fetching for instant page-transitions, loading indicators, and smaller network payloads. However, these advantages require that your website either (a) requires a web server or service that understands MyST sites; or (b) is changed to an HTML export that does not include these features but does allow you to host static files on services like GitHub pages.

Creating Static HTML¶

To create a static HTML export of your MyST site, build it as HTML:

myst build --html

After the build process, you can see the folder in _build/html, which has all assets for your static website. You can verify that the site is working correctly by starting a static web-server, for example,
npx serve _build/html
which will serve a static version of the site.

version: 1
# Your project must be listed in the same myst.yml configuration
project: ...
site:
  title: Site Title
  # Delete the following `site.projects` configuration:
  # projects:
  #   - slug: nested-folder
  #     path: .

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.

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.

export BASE_URL="/repository_name"

name: MyST GitHub Pages Deploy
on:
  push:
    # Runs on pushes targeting the default branch
    branches: [main]
env:
  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@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - uses: actions/setup-node@v3
        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

Deploying to Curvenote¶

Curvenote provides a free service to host your MyST sites with an up-to-date theme (deployment documentation for MyST sites). The websites are hosted on a curve.space subdomain with your username or a custom domain. To configure the domain(s) add them to your site configuration:

site:
  domains:
    - username.curve.space

You can then deploy the site using:

curvenote deploy

You can also deploy from a GitHub action, which will build your site and then deploy it to Curvenote.

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

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^[3] that will run next time you push your code to the main branch you specified. Ensure that you including setting up your CURVENOTE_TOKEN which can be created from your Curvenote profile.

name: deploy-myst-site
on:
  push:
    branches:
      - main
permissions:
  contents: read
  pull-requests: write
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy 🚀
        uses: curvenote/action-myst-publish@v1
        env:
          CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }}