Deploying your MyST Site

There are two different ways to host MyST websites online.

As a static website. An HTML file is generated for each page at once. The collection of HTML files and website assets can be served from static site hosts (like GitHub Pages, Netlify, and ReadTheDocs).
As an application. A MyST server is run that dynamically generates pages when a user visits them. Your site can be served by a hosting provider that supports applications (like Curvenote or Vercel)

The high-level differences between these approaches are outlined in Table 1.

Table 1:High-Level Comparison of MyST Site Deployment Types

Deployment Type	High Performance	Seamless Updates	Static Hosting
Static website	❌	❌	✅
MyST server	✅	✅	❌

The choice between static hosts and application-based hosts often comes down to the type of website hosting that is available, and the amount of complexity that you’re willing to deal with in deploying your site. The sections below share a few considerations to help you make a decision.

Static Websites¶

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.

Static sites should have an index.html

Your 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: .

Custom domains and the base URL¶

When deploying static HTML to the web, you may have to specify a Base URL so that links resolve properly. This happens when you serve your MyST site from a subfolder of a parent URL. For example:

mysite.org/: Does not require a BASE_URL to be set, because the root site is where your MyST site lives.
mysite.org/docs/: Does require a BASE_URL to be set, because your MyST HTML files will be in docs/, not the root.

If MyST detects an environment variable called BASE_URL it will prepend it to all links.

For example, the following example first defines a BASE_URL parameter and then builds the MyST HTML assets.

export BASE_URL="/repository_name"
myst build --html

Services for Static Web Hosting¶

The contents of the _build/html can be served from any static web server. The following articles outline the process of deploying your static site to well-known website providers:

GitHub Pages

Deploy as a static site to GitHub pages using an action.

Netlify

Deploy to Netlify as static HTML, and pull-request previews.

Application Websites¶

Creating Structured Site Data¶

MyST servers consume structured data that represents a MyST website. These data can be built using the myst build command,

myst build --site

which populates the _build/site directory with information about your website including the metadata, cross-references, static images, and MyST AST.

Deploying to a MyST-Aware Server¶

Curvenote

Deploy to Curvenote as a dynamic site with a managed MyST theme.

Websites

Downloads & Static Files

Websites

Github Pages