ManageNavigation

Managing the navigation menu

This page only briefly introduces how to add links to the navigation menu and is for lay audience. For anything more than that, editors are encouraged to look up the corresponding documentations at MkDocs and Material for MkDocs, which include advanced customization features.

The navigation menu in the iDEC wiki is configured in the mkdocs.yml configuration file.

Explanation

Upon opening the mkdocs.yml file, scroll to the bottom and you should see:

nav:
  - Home: index.md
  - Resources:
      - Introduction:
          - resources/introduction.md
      - Creating genetic diversity:
          - resources/genetic_diversity.md
          - Error-prone PCR: resources/epPCR.md
          # ... abridged
  - Team Wiki:
      - team_wiki/team_wiki_home.md

Which corresponds to:

Comparing this to the current site and you should see that, the first level of list items are shown in the navigation tabs (the horizontal menu bar under the website header). Then, in the "Resources" section, the subpages and subsections "Introduction" and "Creating genetic diversity" are listed on the lefthand side navigation menu.

If you want to add a link to a page, add a list item under the nav section:
- {link display name}: {relative path to the .md file to be rendered as webpage}

The relative path is "relative" to the docs folder.
Note that the list item must start with a - dash.
Also note the inclusion of whitespaces, failure to do so might result in links not being properly rendered.

Subpages

To indicate the parent-child relationships between pages, use indentation in the nav list. In the example below, to make the pages "Subpage 1" and "Supage 2" as a child page under "Section Header 1", we put exactly 4 whitespaces in front of the - dash symbols of both list items.

nav:
  # ... abridged
  - Team Wiki:
      - team_wiki/team_wiki_home.md
      - Section Header 1:
          - Subpage 1: team_wiki/subpage1.md
          - Subpage 2: team_wiki/subpage2.md

This would give:

Note that in this example, "Section Header 1" does not link to any place. Clicking on "Section Header 1" only toggles between the expanded and collapsed states of the submenu, which will contain the links to "Subpage 1" and "Subpage 2".

Section index page

In this wiki, through the mkdocs-section-index plugin, we enabled a feature known as section index page. This is to say, the section header itself can be linked to a page. In the example below, to create a page for "Section Header 1", simply insert a list item with only the relative path of the page. The list item should be indented to the Section Header 1" item.

nav:
  # ... abridged
  - Team Wiki:
      - team_wiki/team_wiki_home.md
      - Section Header 1:
          - team_wiki/section1.md
          - Subpage 1: team_wiki/subpage1.md
          - Subpage 2: team_wiki/subpage2.md

Clicking on the "Section Header 1" would therefore lead to a parent page: