Web Navigation, Structure, and Menus

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:

• 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:

- title: Custom title
  url: /path/to/document

- title: Custom title
  url: https://somelink.org

- title: Dropdown title
  children:
  - title:
    url: /pageone
  - title:
    url: /pagetwo

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:

- title: Custom title
  url: path/to/myfile.png

- title: Custom title
  url: https://somelink.org`

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.

Footer¶

You can add a site-wide footer by using site “parts”. Add a footer part to your myst.yml like so:

site:
  parts:
    footer: footer.md

The contents of footer.md will be rendered at the bottom of each page. It will be parsed similarly to other MyST content (though some functionality like code execution will not work).

Style your footer¶

By default footers have style that is similar to the rest of your document. To define a different style (e.g., a multi-column footer with links), use a combination of {grid} and button elements, along with a custom CSS style sheet. Footers are wrapped in a div with class .footer, which can be used in CSS to select items for styling.

For example, the following myst.yml configuration adds a footer.css file that can be used to define the look and feel of your footer.

site:
  options:
    style: ./css/footer.css
  parts:
    footer: footer.md

An example custom footer¶

The example landing page includes a footer.md and ./css/footer.css that you can customize.