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 --htmlAfter 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.
Static sites should have an index.html
index.htmlYour site should be configured with a single project at the root, this can be done by removing the site.projects list so that the site builds at the root url, rather than in a nested folder.
If your project is configured to be in a nested folder using a project slug, a site index will not be created and your project will be instead accessible at a nested slug.
To fix this, change your site configuration to use a flat rather than nested project:
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: .Ignore the _build folder in Git
_build folder in GitIf you are using Git, add the _build folder to your .gitignore so that it is not tracked. This folder contains auto-generated assets that can easily be re-built -- for example in a Continuous Integration system like GitHub Actions.
Deployment Targets¶
Deploy as a static site to GitHub pages using an action.
Deploy to Curvenote as a dynamic site with a managed MyST theme.
Deploy to Netlify as static HTML, and pull-request previews.
