Web templates allow MyST to render documents as HTML-based sites.
These provide different reading experiences that are designed for different types of MyST documents.
They are defined via the same templating system used for static document exporting, and a base set of web themes can be found in the jupyter-book/myst-theme
repository.
Themes bundled with MyST¶
There are two templates for MyST websites, a book-theme
, which is the default and is based loosely on Jupyter Book and an article-theme
that is designed for scientific documents with supporting notebooks. The documentation for this site uses the book-theme
. For a demonstration of the article-theme
, you can see an article on finite volume.
Article Theme¶
The article theme is centered around a single document with supporting content, which is how many scientific articles are structured today: a narrative article with associated computational notebooks to reproduce a figure, document data-cleaning steps, or provide interactive visualization. These are listed as “supporting documents” in this theme and can be pulled in as normal with your Table of Contents. For information on how to import your figures into your article, see Embed and Reuse Jupyter Outputs.
The frontmatter that is displayed at the top of the article is the contents of your project, including a project thumbnail and banner. The affiliations for your authors, their ORCID, email, etc. are available by clicking directly on the author name.
Change Site Templates¶
To manually specify your website template, use the site.template
property:
1 2 3 4
project: ... site: template: article-theme
Change the template
property to article-theme
.
Site navigation¶
In addition to your MyST document’s Table of Contents, you may specify a top-level navigation for your MyST site. These links are displayed across all pages of your site, and are useful for quickly jumping to sections of your site, or for external links.
Specify top-level navigation with the site.nav
option, and provide a collection of navigation links similar to how the Table of Contents is structured. For example:
site:
nav:
# A top-level dropdown
- title: Dropdown links
children:
- title: Page one
url: https://mystmd.org
- title: Page two
url: https://mystmd.org/guide
# A top-level link
- title: A standalone link
url: https://jupyter.org
Action buttons¶
Action buttons provide a more noticeable button that invites users to click on them. They are located in the top-right of the page.
Add action buttons to your site header with the site.actions
option. For example:
site:
actions:
- title: Button text
url: https://mystmd.org
- title: Second button text
url: https://mystmd.org/guide
Site Options¶
Site options allow you to configure a theme’s behavior.[1]
These should be placed in the site.options
in your myst.yml
.
For example:
site:
options:
favicon: my-favicon.ico
logo: my-site-logo.svg
Below is a table of options for each theme bundled with MyST.
book-theme
template¶
Simple site for displaying multiple articles and notebooks with a table of contents.
- Options
- hide_toc (boolean)
Hide the table of contents
- hide_footer_links (boolean)
Hide the previous/next links in the footer
- hide_outline (boolean)
Hide the document outline on all pages
- hide_title_block (boolean)
Hide the document title on all pages
- outline_maxdepth (number)
The maximum depth to show on the document outline, for example,
2
would show only two depths of headings (e.g.<H1>
and<H2>
).- twitter (string)
Twitter handle related to the site
- favicon (file)
Local path to favicon image
- logo (file)
Local path to logo image
- logo_dark (file)
Local path to logo image for dark mode
- logo_text (string)
Short text to display next to logo at the top of all pages
- analytics_google (string)
Google analytics key
- analytics_plausible (string)
Plausible analytics key
- numbered_references (boolean)
Show references as numbered, rather than in APA-style. Only applies to parenthetical citations.
article-theme
template¶
Simple site for displaying an article with associated notebooks.
- Options
- hide_toc (boolean)
Hide the table of contents
- hide_footer_links (boolean)
Hide the previous/next links in the footer
- hide_outline (boolean)
Hide the document outline on all pages
- outline_maxdepth (number)
The maximum depth to show on the document outline, for example,
2
would show only two depths of headings (e.g.<H1>
and<H2>
).- twitter (string)
Twitter handle related to the site
- favicon (file)
Local path to favicon image
- logo (file)
Local path to logo image
- logo_dark (file)
Local path to logo image for dark mode
- logo_text (string)
Short text to display next to logo at the top of all pages
- analytics_google (string)
Google analytics key
- analytics_plausible (string)
Plausible analytics key
- numbered_references (boolean)
Show references as numbered, rather than in APA-style. Only applies to parenthetical citations.
Other top-level site configuration¶
There are some other top-level site configuration options not documented here. You can find them in the following two files.
They are generally unique to the theme (and thus in a dediated
site.options
key rather than a top-level option insite
).