notes/docs/navigation-structure.md

layout	title	nav_order
default	Navigation Structure	5

Navigation Structure

{: .no_toc }

Table of contents

{: .text-delta } 1. TOC {:toc}

---

Main navigation

The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).

By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see Pages with Children).

---

Ordering pages

To specify a page order, use the nav_order parameter in your pages' YAML front matter.

Example

{: .no_toc }

---
layout: default
title: Customization
nav_order: 4
---

The specified nav_order parameters on a site should be all integers or all strings. Pages without a nav_order parameter are ordered alphabetically by their title, and appear after the explicitly-ordered pages at each level. By default, all Capital letters are sorted before all lowercase letters; adding nav_sort: case_insensitive in the configuration file ignores case when sorting strings (but also sorts numbers lexicographically: 10 comes before 1).

---

Excluding pages

For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the nav_exclude: true parameter in the YAML front matter for that page.

Example

{: .no_toc }

---
layout: default
title: 404
nav_exclude: true
---

---

Pages with children

Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the ./docs directory and each of the sections in subdirectories like ./docs/ui-components and ./docs/utilities. This gives us an organization like:

+-- ..
|-- (Jekyll files)
|
|-- docs
|   |-- ui-components
|   |   |-- index.md  (parent page)
|   |   |-- buttons.md
|   |   |-- code.md
|   |   |-- labels.md
|   |   |-- tables.md
|   |   +-- typography.md
|   |
|   |-- utilities
|   |   |-- index.md      (parent page)
|   |   |-- color.md
|   |   |-- layout.md
|   |   |-- responsive-modifiers.md
|   |   +-- typography.md
|   |
|   |-- (other md files, pages with no children)
|   +-- ..
|
|-- (Jekyll files)
+-- ..

On the parent pages, add this YAML front matter parameter:

• has_children: true (tells us that this is a parent page)

Example

{: .no_toc }

---
layout: default
title: UI Components
nav_order: 2
has_children: true
---

Here we're setting up the UI Components landing page that is available at /docs/ui-components, which has children and is ordered second in the main nav.

Child pages

{: .text-gamma }

On child pages, simply set the parent: YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).

Example

{: .no_toc }

---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
---

The Buttons page appears as a child of UI Components and appears second in the UI Components section.

Auto-generating Table of Contents

By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set has_toc: false in the parent page's YAML front matter.

Example

{: .no_toc }

---
layout: default
title: UI Components
nav_order: 2
has_children: true
has_toc: false
---

Children with children

{: .text-gamma }

Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.

1. Add the has_children attribute to the child
2. Add the parent and grand_parent attribute to the grandchild

Example

{: .no_toc }

---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
has_children: true
---

---
layout: default
title: Buttons Child Page
parent: Buttons
grand_parent: UI Components
nav_order: 1
---

This would create the following navigation structure:

+-- ..
|
|-- UI Components
|   |-- ..
|   |
|   |-- Buttons
|   |   |-- Button Child Page
|   |
|   |-- ..
|
+-- ..

---

Auxiliary Links

To add auxiliary links to your site (in the upper right on all pages), add it to the aux_links [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-links) in your site's _config.yml file.

Example

{: .no_toc }

# Aux links for the upper right navigation
aux_links:
  "Just the Docs on GitHub":
    - "//github.com/pmarsceill/just-the-docs"

---

In-page navigation with Table of Contents

To generate a Table of Contents on your docs pages, you can use the {:toc} method from Kramdown, immediately after an <ol> in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the {: .no_toc } CSS class.

Example

{: .no_toc }

# Navigation Structure
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

This example skips the page name heading (#) from the TOC, as well as the heading for the Table of Contents itself (##) because it is redundant, followed by the table of contents itself. To get an unordered list, replace 1. TOC above by - TOC.

Collapsible Table of Contents

The Table of Contents can be made collapsible using the <details> and <summary> elements , as in the following example. The attribute open (expands the Table of Contents by default) and the styling with {: .text-delta } are optional.

<details open markdown="block">
  <summary>
    Table of contents
  </summary>
  {: .text-delta }
1. TOC
{:toc}
</details>

The result is shown at the top of this page ({:toc} can be used only once on each page).