mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-10 14:01:22 -06:00
8f0bcd6875
Added link and short blurb about document collections to the navigation structure page, for quicker reference and suggestion during reading documentation. Allows easier reference when trying to create page groups / categories without using a blank Parent page. Avoids automatically folded Parent page when Child pages are the necessary ones.
365 lines
10 KiB
Markdown
365 lines
10 KiB
Markdown
---
|
|
layout: default
|
|
title: Navigation Structure
|
|
nav_order: 5
|
|
---
|
|
|
|
# Navigation Structure
|
|
{: .no_toc }
|
|
|
|
<details open markdown="block">
|
|
<summary>
|
|
Table of contents
|
|
</summary>
|
|
{: .text-delta }
|
|
- TOC
|
|
{:toc}
|
|
</details>
|
|
|
|
---
|
|
|
|
## Main navigation
|
|
|
|
The main navigation for your Just the Docs site is on the left side of the page on 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](#pages-with-children)).
|
|
|
|
---
|
|
|
|
## Ordering pages
|
|
|
|
To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
|
|
|
|
### Example (ordering pages)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
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. Pages with numerical `nav_order` parameters always come before those with string `nav_order` parameters. When you omit `nav_order` parameters, they default to the titles of the pages. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages. All pages with explicit `nav_order` parameters
|
|
come before all pages ordered by their `title` values.
|
|
|
|
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 (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example.
|
|
|
|
---
|
|
|
|
## 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 (excluding pages)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
layout: default
|
|
title: 404
|
|
nav_exclude: true
|
|
---
|
|
|
|
```
|
|
|
|
The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
|
|
|
|
Pages with no `title` are automatically excluded from the main 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 (parent pages)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
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 (child pages)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
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.
|
|
|
|
### Ordering child pages
|
|
{: .d-inline-block }
|
|
|
|
New (v0.4.0)
|
|
{: .label .label-green }
|
|
|
|
You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
|
|
|
|
- `child_nav_order: reversed`
|
|
|
|
#### Example (ordering child pages)
|
|
{: .no_toc }
|
|
```yaml
|
|
---
|
|
layout: default
|
|
title: Reversed Child Pages
|
|
child_nav_order: reversed
|
|
---
|
|
```
|
|
|
|
### 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 (auto-generating Table of Contents)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
1. Add the `parent` and `grand_parent` attribute to the grandchild
|
|
|
|
##### Example (children within children)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
---
|
|
layout: default
|
|
title: Buttons
|
|
parent: UI Components
|
|
nav_order: 2
|
|
has_children: true
|
|
---
|
|
|
|
```
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
| |
|
|
| |-- ..
|
|
|
|
|
+-- ..
|
|
```
|
|
|
|
{: .note }
|
|
Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.
|
|
|
|
---
|
|
|
|
## Grouping pages with collections
|
|
|
|
Pages can also be grouped together by using Jekyll's and Just the Docs's [collections]({% link docs/configuration.md %}#document-collections) feature. In contrast to using [pages with children](#pages-with-children), pages grouped by collection are grouped by a shared header (the name of the collection) instead of a page.
|
|
|
|
The `nav_fold` configuration option works for collection-grouped pages. For more information, please refer to the [collections documentation]({% link docs/configuration.md %}#document-collections).
|
|
|
|
### Example (grouping by collection)
|
|
{: .no_toc }
|
|
|
|
The following example sets up two collections, `collection-one` and `collection-two`:
|
|
|
|
- any document placed within `_collection-1/` will be grouped under the `Collection One` header by default. Since `nav_fold` is set to `true`, the pages will be folded by default.
|
|
- any document placed within `_collection-2/` will be grouped under the `Collection Two` header by default. Since `nav_fold` is set to `false`, the pages will be expanded by default.
|
|
|
|
```yaml
|
|
_config.yml:
|
|
collections:
|
|
collection-one:
|
|
permalink: "/:collection/:path/"
|
|
output: true
|
|
collection-two:
|
|
permalink: "/:collection/:path/"
|
|
output: true
|
|
just_the_docs:
|
|
collections:
|
|
collection-one:
|
|
name: Collection One
|
|
nav_fold: true
|
|
collection-two:
|
|
name: Collection Two
|
|
nav_fold: false
|
|
```
|
|
---
|
|
|
|
## Auxiliary Links
|
|
|
|
To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
|
|
|
|
### Example (auxiliary links)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
# Aux links for the upper right navigation
|
|
aux_links:
|
|
"Just the Docs on GitHub":
|
|
- "//github.com/just-the-docs/just-the-docs"
|
|
```
|
|
|
|
---
|
|
|
|
## External Navigation Links
|
|
{: .d-inline-block }
|
|
|
|
New (v0.4.0)
|
|
{: .label .label-green }
|
|
|
|
To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
|
|
External links will appear in the navigation after the links to ordinary pages, but before any collections.
|
|
|
|
### Example (external navigation links)
|
|
{: .no_toc }
|
|
|
|
```yaml
|
|
# External navigation links
|
|
nav_external_links:
|
|
- title: Just the Docs on GitHub
|
|
url: https://github.com/just-the-docs/just-the-docs
|
|
hide_icon: false # set to true to hide the external link icon - defaults to false
|
|
opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
|
|
```
|
|
|
|
### Opening external links in a new tab
|
|
{: .d-inline-block }
|
|
|
|
New (unreleased)
|
|
{: .label .label-green }
|
|
|
|
The external links are decorated by an icon, which distinguishes them from internal links.
|
|
You can suppress the icon by setting `hide_icon: true`.
|
|
|
|
By default, external links are not opened in a new tab. However, this can be enabled by:
|
|
|
|
1. setting `opens_in_new_tab: true` in the link's configuration object
|
|
2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
|
|
|
|
When they conflict, `opens_in_new_tab` takes precedence.
|
|
|
|
---
|
|
|
|
## 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 (in-page navigation with Table of Contents)
|
|
{: .no_toc }
|
|
|
|
```markdown
|
|
# 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.
|
|
|
|
```markdown
|
|
<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](#navigation-structure) (`{:toc}` can be used only once on each page).
|