Adjusted the documentation to explain how mixtures of numbers and strings are treated by `nav_order`.
6.9 KiB
layout | title | nav_order |
---|---|---|
default | Navigation Structure | 5 |
Navigation Structure
{: .no_toc }
Table of contents
{: .no_toc .text-delta }
- 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, you can use the nav_order
parameter in your pages' YAML front matter.
Example
{: .no_toc }
---
layout: default
title: Customization
nav_order: 4
---
The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
The parameter values can be numbers (integers, floats) and/or strings. When you omit nav_order
parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical nav_order
parameters always come before those with strings or default nav_order
parameters. If you want to make the page order independent of the page titles, you can set explicit nav_order
parameters on all pages.
By default, all Capital letters come before all lowercase letters; you can add nav_sort: case_insensitive
in the configuration file to ignore the case). Enclosing strings in quotation marks is optional.
Note for users of previous versions:
nav_sort: case_insensitive
previously affected the ordering of numericalnav_order
parameters: e.g.,10
came before2
. Also, all pages with explicitnav_order
parameters previously came before all pages with default parameters.
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 no title
are automatically excluded from the navigation.
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.
- Add the
has_children
attribute to the child - Add the
parent
andgrand_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).