In the default MyST templates there are several sections of the page that help your users navigate within and between pages. Here’s how you can configure them.
Website Layout¶
The default MyST themes are divided into five main sections:
The layout of the default MyST web themes. Other themes may have slightly different structure.
- Header: Contains top-level site navigation.
- Primary sidebar: Cross-page navigation defined in the Table of Contents.
- Content window: Contains content and metadata for the current page.
- Secondary sidebar: Contains in-page navigation and links.
- Footer: (work in progress) Contains more in-depth site navigation.
Header¶
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:
- title: Internal page
url: /website-metadata
There are a few types of entries you can define:
Type | Pattern | Description |
---|---|---|
Internal paths |
| A path to an internal page. This should begin with / . Do not include the file extension of the page! |
External URLs |
| Direct links to an external website. This should be a fully-specified URL. |
Dropdowns |
| Becomes a dropdown with other entries inside. |
Action Buttons¶
Action buttons provide a more noticeable button that invites users to click on them.
Add action buttons to your site header with the site.actions
option.
For example:
site:
actions:
- title: A URL
url: https://mystmd.org
There are two types of actions:
Type | Pattern | Description |
---|---|---|
Static downloads |
| A path to an internal file. This turns the button into a download link for the file. |
External URLs |
| Direct links to an external website. This should be a fully-specified URL. |
Primary sidebar (Table of Contents)¶
Is defined by your MyST Project Table of Contents.
Hide the primary sidebar¶
To hide the Primary Sidebar, use site.options.hide_toc
like so:
site:
options:
hide_toc: true
Content window¶
Is populated with page-level metadata and your page’s content. See Frontmatter for many kinds of metadata that configure this section.
Use the Edit this Page button¶
If you’ve added github
MyST frontmatter, the MyST themes will display an “Edit this page” link for your page. This link will point to the source file for your page in GitHub, allowing a reader to quickly view the source and make an edit using GitHub’s UI.
To override this behavior and set a manual edit URL, use the edit_url
field in MyST frontmatter.
To disable the Edit this page
button, set the value of edit_url
to null
.
Secondary sidebar¶
Contains the in-page navigation of the page, autopopulated by the page’s header structure.
Hide the secondary sidebar¶
To hide the secondary sidebar, use the site.options.hide_outline
option:
site:
options:
hide_outline: true
Make content expand to the right margin¶
To make content take up the empty space to the right of the content (where the secondary sidebar usually lives), attach the col-page-right
CSS class (one of the built-in CSS classes) to a page block or element.
Here’s an example of attaching the class directly to an admonition:
```{note} This note will spread to the right!
:class: col-page-right
Yes it will!
```
You could also attach the CSS class to a content block.