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:
  - url: pageone
  - 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.

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

Footer¶