From dd0b814bfdcdcbfdd39af29dd47830d31b56b658 Mon Sep 17 00:00:00 2001
From: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 20 Aug 2024 22:50:47 +0200
Subject: [PATCH] Docs: Allow unlimited multi-level navigation (#1440)

* Remove `jekyll-default-layout` plugin

* Move docs/navigation-structure to docs/navigation

* Fix uses of line-nos in md files

* Update CHANGELOG.md

---------

Co-authored-by: Matt Wang <matt@matthewwang.me>
---
 CHANGELOG.md                                  |   3 +-
 MIGRATION.md                                  |   4 +-
 _config.yml                                   |   8 +
 docs/configuration.md                         |   5 +-
 docs/customization.md                         |   3 +-
 docs/index-test.md                            |   1 -
 docs/layout/layout.md                         |   7 +-
 docs/layout/minimal/minimal.md                |   1 -
 docs/navigation-structure.md                  | 364 ------------------
 docs/navigation/auxiliary.md                  |  17 +
 docs/navigation/children.md                   |  21 +
 docs/navigation/in-page.md                    |  84 ++++
 docs/navigation/index.md                      |  16 +
 docs/navigation/main/ancestry.md              |  51 +++
 docs/navigation/main/collections.md           |  67 ++++
 docs/navigation/main/exclude.md               |  29 ++
 docs/navigation/main/external.md              |  33 ++
 docs/navigation/main/index.md                 |  41 ++
 docs/navigation/main/levels.md                | 123 ++++++
 docs/navigation/main/order.md                 |  35 ++
 docs/navigation/main/x.md                     |  10 +
 docs/navigation/main/xs.md                    |  10 +
 docs/navigation/main/xt.md                    |  12 +
 docs/navigation/main/xu.md                    |  12 +
 docs/navigation/main/y.md                     |  10 +
 docs/navigation/main/ys.md                    |  10 +
 docs/navigation/main/yt.md                    |  12 +
 docs/navigation/main/yu.md                    |  12 +
 docs/navigation/parents.md                    |  11 +
 docs/search.md                                |   1 -
 docs/ui-components/buttons.md                 |   1 -
 docs/ui-components/callouts.md                |   1 -
 docs/ui-components/{code.md => code/index.md} |   4 +-
 .../{line-nos.md => code/line-numbers.md}     |   8 +-
 .../{ui-components.md => index.md}            |   3 -
 docs/ui-components/labels.md                  |   1 -
 docs/ui-components/lists.md                   |   1 -
 docs/ui-components/tables.md                  |   1 -
 docs/ui-components/typography.md              |   1 -
 docs/utilities/color.md                       |   1 -
 docs/utilities/{utilities.md => index.md}     |   3 -
 docs/utilities/layout.md                      |   1 -
 docs/utilities/responsive-modifiers.md        |   1 -
 docs/utilities/typography.md                  |   1 -
 index.md                                      |   2 +-
 45 files changed, 638 insertions(+), 405 deletions(-)
 delete mode 100644 docs/navigation-structure.md
 create mode 100644 docs/navigation/auxiliary.md
 create mode 100644 docs/navigation/children.md
 create mode 100644 docs/navigation/in-page.md
 create mode 100644 docs/navigation/index.md
 create mode 100644 docs/navigation/main/ancestry.md
 create mode 100644 docs/navigation/main/collections.md
 create mode 100644 docs/navigation/main/exclude.md
 create mode 100644 docs/navigation/main/external.md
 create mode 100644 docs/navigation/main/index.md
 create mode 100644 docs/navigation/main/levels.md
 create mode 100644 docs/navigation/main/order.md
 create mode 100644 docs/navigation/main/x.md
 create mode 100644 docs/navigation/main/xs.md
 create mode 100644 docs/navigation/main/xt.md
 create mode 100644 docs/navigation/main/xu.md
 create mode 100644 docs/navigation/main/y.md
 create mode 100644 docs/navigation/main/ys.md
 create mode 100644 docs/navigation/main/yt.md
 create mode 100644 docs/navigation/main/yu.md
 create mode 100644 docs/navigation/parents.md
 rename docs/ui-components/{code.md => code/index.md} (98%)
 rename docs/ui-components/{line-nos.md => code/line-numbers.md} (96%)
 rename docs/ui-components/{ui-components.md => index.md} (79%)
 rename docs/utilities/{utilities.md => index.md} (84%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1466afcce..a77d8aeb3d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,9 +23,10 @@ Code changes to `main` that are *not* in the latest release:
 
 Docs changes made since the latest release:
 
-- N/A
+- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440]
 
 [#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431
+[#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440
 
 ## Release v0.9.0
 
diff --git a/MIGRATION.md b/MIGRATION.md
index f134c7f32f..ee133cacf9 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -41,7 +41,7 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 > and pull the changes of a new release to your clone,
 > you may need to resolve merge conflicts.
 
-[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
+[CHANGELOG]: {% link CHANGELOG.md %}
 
 ## v0.6.x - v0.7.0
 
@@ -373,7 +373,7 @@ For changes since v0.3.3, the log usually references the merged PR that made the
 
 #### Configuration
 
-- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more.
+- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more.
 - Multiple Google Analytics tags are now supported. PR: [#1029]
 
 #### Customization
diff --git a/_config.yml b/_config.yml
index 54c9bd1048..23b9a9b5bc 100644
--- a/_config.yml
+++ b/_config.yml
@@ -21,6 +21,14 @@ repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
 
+defaults:
+  -
+    scope:
+      path: "docs" # an empty string here means all files in the project
+      type: "pages"
+    values:
+      layout: "default"
+
 exclude:
  # from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
    - .sass-cache/
diff --git a/docs/configuration.md b/docs/configuration.md
index d0f4f14015..eaa763c51a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Configuration
 nav_order: 2
 ---
@@ -87,7 +86,7 @@ mermaid:
 
 Provide a `path` instead of a `version` key to load the mermaid library from a local file.
 
-See [the Code documentation]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
+See [the Code documentation]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
 
 ## Aux links
 
@@ -126,7 +125,7 @@ New (v0.4.0)
 {: .label .label-green }
 
 External links can be added to the navigation through the `nav_external_links` option.
-See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+See [Navigation Structure]({% link docs/navigation/main/external.md %}) for more details.
 
 ## Footer content
 
diff --git a/docs/customization.md b/docs/customization.md
index 4939e1872a..8d70b44693 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Customization
 nav_order: 6
 ---
@@ -178,7 +177,7 @@ New (v0.4.0)
 
 `_includes/toc_heading_custom.html`
 
-If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
+If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation/children.md %}) after the page's content.
 
 #### Example
 {: .no_toc }
diff --git a/docs/index-test.md b/docs/index-test.md
index 522a1188d4..7e0c62b044 100644
--- a/docs/index-test.md
+++ b/docs/index-test.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Markdown kitchen sink
 nav_order: 99
 ---
diff --git a/docs/layout/layout.md b/docs/layout/layout.md
index 832cbb131b..5313bc6f2e 100644
--- a/docs/layout/layout.md
+++ b/docs/layout/layout.md
@@ -2,7 +2,6 @@
 title: Layout
 layout: default
 nav_order: 4.5
-has_children: true
 ---
 
 # Layout
@@ -18,11 +17,11 @@ You can use [Jekyll's front matter defaults] to specify the same layout for many
 
 ## The `default` layout
 
-This page uses the default layout.
+This page uses the default layout. This site configures `layout: default` as a [front matter default](https://jekyllrb.com/docs/configuration/front-matter-defaults/) value for all pages in the `docs` directory.
 
-It is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
+The default layout of Just the Docs is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button.
 
-Each child (and grandchild) page of a top-level page has so-called *breadcrumbs*: links to its parent (and grandparent) pages. It shows the breadcrumbs above the main content of the page.
+All pages except top-level pages automatically have a list of  so-called *breadcrumbs*: links to their parent pages and any higher-level ancestors. They show the breadcrumbs above the main content of the page.
 
 Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content.
 
diff --git a/docs/layout/minimal/minimal.md b/docs/layout/minimal/minimal.md
index 1821d6713c..b2b713c41b 100644
--- a/docs/layout/minimal/minimal.md
+++ b/docs/layout/minimal/minimal.md
@@ -2,7 +2,6 @@
 title: A minimal layout page
 layout: minimal
 parent: Layout
-has_children: true
 ---
 
 # A minimal layout page
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
deleted file mode 100644
index ad2c4a5ccc..0000000000
--- a/docs/navigation-structure.md
+++ /dev/null
@@ -1,364 +0,0 @@
----
-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).
diff --git a/docs/navigation/auxiliary.md b/docs/navigation/auxiliary.md
new file mode 100644
index 0000000000..d1e4818ce3
--- /dev/null
+++ b/docs/navigation/auxiliary.md
@@ -0,0 +1,17 @@
+---
+title: Auxiliary Links
+parent: Navigation
+nav_order: 2
+---
+
+# Auxiliary Links
+
+You can add a list of auxiliary links to your site, shown at the top right on all pages. You do this by including the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
+
+#### Example
+
+```yaml
+aux_links:
+  Just the Docs on GitHub:
+    - https://github.com/just-the-docs/just-the-docs
+```
diff --git a/docs/navigation/children.md b/docs/navigation/children.md
new file mode 100644
index 0000000000..481320542d
--- /dev/null
+++ b/docs/navigation/children.md
@@ -0,0 +1,21 @@
+---
+title: Child Pages
+parent: Navigation
+nav_order: 4
+---
+
+# Child Pages
+
+By default, all parent pages will automatically have a so-called 'Table of Contents' at the bottom, showing links to all their child pages.
+
+To disable this automatic list, set `has_toc: false` in the parent page's front matter.
+
+#### Example
+
+```yaml
+---
+title: UI Components
+nav_order: 3
+has_toc: false
+---
+```
diff --git a/docs/navigation/in-page.md b/docs/navigation/in-page.md
new file mode 100644
index 0000000000..b84a95b678
--- /dev/null
+++ b/docs/navigation/in-page.md
@@ -0,0 +1,84 @@
+---
+title: In-Page Navigation
+parent: Navigation
+nav_order: 5
+---
+
+# In-Page Navigation
+{: .no_toc }
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+To support in-page navigation, you can generate a *Table of Contents* (TOC) with links to headings, like the one shown above, as well as a link to the top of the page.
+
+## Table of Contents
+
+To generate a *Table of Contents* in a page, you use Kramdown's `{:toc}` method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels.
+
+If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names).
+
+#### Example 
+{: .no_toc }
+
+```markdown
+# In-Page Navigation
+{: .no_toc }
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+```
+
+This example omits the top-level heading (`In-Page Navigation`) from the TOC, as well as the heading for the *Table of Contents* itself.
+
+To get an unordered list, replace `1. TOC` by `- TOC` in the above example.
+
+## Collapsible Table of Contents
+
+You can make the Table of Contents collapsible using the `<details>` and `<summary>` elements, as in the following example.
+
+#### Example
+{: .no_toc }
+
+```markdown
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+```
+
+The attribute `open` (which expands the Table of Contents by default) and the styling (here with `text-delta`) are optional.
+
+{: .note }
+`{:toc}` can be used only once on each page.
+
+## Back to Top {#back-to-top-doc}
+
+{: .warning }
+The default id for a section with heading "Back to Top" is `"back-to-top"`.
+To avoid invalid HTML, sites that set the `back_to_top` configuration variable
+should override the default id for such sections. The Markdown source file for
+the current page uses `## Back to Top {#back-to-top-doc}`.
+
+You can add a link from the bottom of each page to its top. You do this by including the `back_to_top` configuration option in your site's `_config.yml` file, together with `back_to_top_text` for the anchor link.
+
+### Example
+{: .no_toc }
+
+```yaml
+back_to_top: true
+back_to_top_text: "Back to top"
+```
+
+{: .warning }
+Back-to-top links currently appear only when *other* configuration options require footer generation!
diff --git a/docs/navigation/index.md b/docs/navigation/index.md
new file mode 100644
index 0000000000..dee0d65e1e
--- /dev/null
+++ b/docs/navigation/index.md
@@ -0,0 +1,16 @@
+---
+title: Navigation
+nav_order: 5
+---
+
+# Navigation
+
+The default page layout supports various navigation features:
+
+* a **main navigation** panel, highlighting the currently selected page;
+* a list of **auxiliary** links, shown on all pages;
+* lists of **breadcrumbs**, shown on all except top level pages;
+* optional lists of links to **child pages** (so-called 'tables of contents'); and
+* section heading links for **in-page navigation**, with an optional **back-to-top** link.
+
+See the following pages for how to specify these features, with illustrative examples.
diff --git a/docs/navigation/main/ancestry.md b/docs/navigation/main/ancestry.md
new file mode 100644
index 0000000000..8b7dac09f4
--- /dev/null
+++ b/docs/navigation/main/ancestry.md
@@ -0,0 +1,51 @@
+---
+title: Ancestry
+parent: Main Navigation
+nav_order: 4
+---
+
+# Ancestry
+
+If no two pages on your website have the same `title`, you only need to set the `parent` titles to fix the hierarchy. You can also have the same `title` on pages that have no children, provided that they have different parent pages.
+
+If two parents have the same `title`, but different grandparents, you can set their `grand_parent` titles to distinguish between their parents. The `grand_parent` title needs to be the same as the `parent` of the `parent`.
+
+#### Example
+
+```yaml
+---
+title: T
+parent: S
+grand_parent: X
+---
+```
+
+```yaml
+---
+title: T
+parent: S
+grand_parent: Y
+---
+```
+
+The `ancestor` field of a page generalizes `grand_parent` to higher levels.
+
+The following pages illustrate `parent` disambiguation using `grand_parent` and `ancestor` titles. Some descendants of both [Page X][X] and [Page Y][Y] have the same title, so references to those descendants as `parent` always require disambiguation.
+
+- [X][X] is a parent page
+- [S][XS] is the only child of [X][X]. The `parent` reference to [X][X] is unambiguous.
+- [T][XT] is the only child of [S][XS]. Its `parent` is disambiguated by its `grand_parent`.
+- [U][XU] is the only child of [T][XT]. Its `parent` is disambiguated by its `ancestor`.
+- [Y][Y] is a sibling of [X][X].
+- [S][YS] is the only child of [Y][Y]. The `parent` reference to [Y][Y] is unambiguous.
+- [T][YT] is the only child of [S][YS]. Its `parent` is disambiguated by its `ancestor`
+- [U][YU] is the only child of [T][YT]. Its `parent` is disambiguated by its `ancestor`.
+
+[X]: {% link docs/navigation/main/x.md %}
+[XS]: {% link docs/navigation/main/xs.md %}
+[XT]: {% link docs/navigation/main/xt.md %}
+[XU]: {% link docs/navigation/main/xu.md %}
+[Y]: {% link docs/navigation/main/y.md %}
+[YS]: {% link docs/navigation/main/ys.md %}
+[YT]: {% link docs/navigation/main/yt.md %}
+[YU]: {% link docs/navigation/main/yu.md %}
diff --git a/docs/navigation/main/collections.md b/docs/navigation/main/collections.md
new file mode 100644
index 0000000000..9ef1bd33bb
--- /dev/null
+++ b/docs/navigation/main/collections.md
@@ -0,0 +1,67 @@
+---
+title: Collections
+parent: Main Navigation
+nav_order: 5
+---
+
+# Collections
+
+By default, the navigation includes only [normal pages](https://jekyllrb.com/docs/pages/).
+However, you can configure Just the Docs to include also pages from [Jekyll collections](https://jekyllrb.com/docs/collections/).
+
+{: .note }
+> You store collection pages in directories that start with an underscore (`_`), e.g., `_tests`. You won't see your `tests` collection pages in the navigation if you store them in a `tests` directory![^1]
+
+[^1]: You can optionally specify a directory to store all your collections. For example, if you specify `collections_dir: my_collections` in `_config.yml`, you should then store the pages of the `tests` collection in the `my_collections/_tests` directory.
+
+#### Example
+
+To define a Jekyll `tests` collection named `Tests` in your main navigation, store its pages in the `_tests` directory, and add the following to `_config.yml`:
+
+```yaml
+collections:
+  tests:
+    output: true
+
+just_the_docs:
+  collections:
+    tests:
+      name: Tests
+```
+
+Together with the `name` to be used for a collection in the navigation, you can configure the following options:
+
+* `nav_exclude: true` to exclude the entire collection from the main navigation
+* `nav_fold: true` to fold the collection, instead of showing links to all its top-level pages[^2]
+* `search_exclude: true` to exclude all the collection pages from search results
+
+[^2]:
+    When JavaScript is disabled in the browser, all folded collections are automatically expanded,
+    since clicking expander symbols has no effect.
+
+The main navigation for all your normal pages (if any) is displayed before those in collections. When *all* your pages are in a single collection, its name is not displayed.
+
+You can configure multiple collections. This creates categories in the main navigation with the configured names.
+
+#### Example
+
+```yaml
+collections:
+  tests:
+    output: true
+  tutorials:
+    output: true
+
+just_the_docs:
+  collections:
+    tests:
+      name: Tests
+      search_exclude: true
+    tutorials:
+      name: Tutorials
+      nav_fold: true
+```
+
+The navigation for each collection is a separate name space for page titles: a page in one collection cannot be the `parent` of a page in a different collection, nor of a normal page.
+
+----
diff --git a/docs/navigation/main/exclude.md b/docs/navigation/main/exclude.md
new file mode 100644
index 0000000000..93f223f73c
--- /dev/null
+++ b/docs/navigation/main/exclude.md
@@ -0,0 +1,29 @@
+---
+title: Excluding Pages
+parent: Main Navigation
+nav_order: 2
+---
+
+# 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) set `nav_exclude: true` in their front matter.
+
+#### Example
+
+```yaml
+---
+layout: default
+title: 404
+nav_exclude: true
+permalink: /404
+---
+```
+
+The `nav_exclude` parameter does not affect the [breadcrumbs]({% link docs/navigation/parents.md %}), nor the [lists of child pages]({% link docs/navigation/children.md %}), which you can use to access pages excluded from the main navigation. 
+
+Pages with no `title` are automatically excluded from the main navigation, except when they are in collections (where Jekyll provides default titles based on file names).
+
+Child pages are automatically excluded from the main navigation when their parent page is excluded.
+
+{: .warning }
+It is currently possible to exclude all the child pages of a page from the main navigation by setting `has_children: false` in its front matter. However, the `has_children` parameter may be ignored altogether in a future release, so it is better to use the `nav_exclude` parameter on each child page.
diff --git a/docs/navigation/main/external.md b/docs/navigation/main/external.md
new file mode 100644
index 0000000000..a0dfd8b55e
--- /dev/null
+++ b/docs/navigation/main/external.md
@@ -0,0 +1,33 @@
+---
+title: External Links
+parent: Main Navigation
+nav_order: 6
+---
+
+# External Links
+
+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
+
+```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
+
+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.
diff --git a/docs/navigation/main/index.md b/docs/navigation/main/index.md
new file mode 100644
index 0000000000..17edaff634
--- /dev/null
+++ b/docs/navigation/main/index.md
@@ -0,0 +1,41 @@
+---
+title: Main Navigation
+parent: Navigation
+nav_order: 1
+---
+
+# Main Navigation
+
+The main navigation for your Just the Docs site is at the left side of the page on large screens, and at the top (behind a tap) on small screens. 
+
+You need to specify the `title` of each page in its front matter. Page titles are independent of file names and directory structure. The navigation uses the title of the page as an anchor for links to the page.
+
+By default, links to all pages appear in the main navigation at the top level, ordered alphabetically by their titles. By adding further fields to the front matter of individual pages, you can [change their order]({% link docs/navigation/main/order.md %}), [exclude pages]({% link docs/navigation/main/exclude.md %}), and change their [parent pages]({% link docs/navigation/main/levels.md %}).
+
+{: .new-title }
+> New (Multi-level)
+>
+> The main navigation can be structured as a multi-level menu of unlimited depth:
+> pages can always have child pages.
+
+For the construction of the navigation display to work (and to avoid potential confusion when browsing) ***the page titles on your site need to satisfy the following requirements:***
+
+* Top-level pages must have different titles.
+* Pages with the same parent must have different titles.
+* The title of each page must be different from the titles of all its child pages, and from the titles of their child pages, etc.
+
+{: .new-title }
+> New (Multi-level)
+>
+> If *all* the pages of your site have different titles, you need only to specify the `title` of each page, and the `parent` title of each lower-level page.[^1]
+
+[^1]: Previous versions of Just the Docs restricted the navigation to three levels. You also needed to specify `has_children: true` on all parent pages, and a `grand_parent` title on all grandchild pages. The `has_children` parameter is now redundant, and the `grand_parent` parameter can usually be omitted.
+
+If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter. 
+
+{: .new-title }
+> New (Multi-level)
+>
+> For deeper navigation structures, you can specify the title of a grandparent or higher level page as an `ancestor` title.
+
+----
diff --git a/docs/navigation/main/levels.md b/docs/navigation/main/levels.md
new file mode 100644
index 0000000000..2855ae824e
--- /dev/null
+++ b/docs/navigation/main/levels.md
@@ -0,0 +1,123 @@
+---
+title: Page Levels
+parent: Main Navigation
+nav_order: 3
+---
+
+# Page Levels
+
+Sometimes you will want to create a page with many children. First, it is recommended that you store related pages together in a directory. For example, in these docs, we keep all of the written documentation pages in the `./docs` directory, and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like this:
+
+{: .lh-0 }
+```
+┌─ ...
+├─ (Jekyll files)
+├─ docs
+    ├─ configuration.md
+    ├─ ui-components
+        ├─ index.md (parent page)
+        ├─ buttons.md
+        ├─ callouts.md
+        ├─ code
+            ├─ index.md (parent page)
+            └─ line-numbers.md
+        ├─ labels.md
+        ├─ tables.md
+        └─ typography.md
+    ├─ ...
+    └─ MIGRATION.md
+├─ index.md (home page)
+├─ (Jekyll files)
+└─ ...
+```
+
+#### Example
+
+```yaml
+---
+title: UI Components
+nav_order: 3
+---
+```
+
+Here we're setting up the UI Components landing page that is available at URL `/docs/ui-components`, which is ordered second in the main navigation.
+
+The navigation links for all pages with children come with an expander. When you click the expander, the display of the children is toggled, so you can expand or collapse all the children displays, regardless of which page is currently active. 
+
+## Child Pages
+
+On child pages, simply set the `parent` front matter to the parent page's `title`, and set a navigation order (relative to pages having the same parent).
+
+#### Example
+
+```yaml
+---
+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 pages.
+
+{: .new-title }
+> New (Multi-level)
+>
+> The `has_children` field is now redundant (and ignored, except when significant for backwards compatibility).
+
+## Multi-level Child Pages
+
+Child pages can themselves have children, to any number of levels. 
+
+#### Example
+
+```yaml
+---
+title: Main Navigation
+parent: Navigation
+nav_order: 1
+---
+```
+
+```yaml
+---
+title: Ancestry
+parent: Main Navigation
+nav_order: 4
+---
+```
+
+```yaml
+---
+title: X
+parent: Ancestry
+---
+```
+
+```yaml
+---
+title: Y
+parent: Ancestry
+---
+```
+
+This creates the following navigation structure:
+
+{: .lh-0 }
+```
+┌─ ...
+├─ ...
+├─ Navigation
+    ├─ ...
+    ├─ Main Navigation
+        ├─ ...
+        ├─ Ancestry
+            ├─ X
+            └─ Y
+        ├─ ...
+        └─ ...
+    ├─ ...
+    └─ ...
+├─ ...
+└─ ...
+```
diff --git a/docs/navigation/main/order.md b/docs/navigation/main/order.md
new file mode 100644
index 0000000000..e2bdaa2132
--- /dev/null
+++ b/docs/navigation/main/order.md
@@ -0,0 +1,35 @@
+---
+title: Ordering Pages
+parent: Main Navigation
+nav_order: 1
+---
+
+# Ordering Pages
+
+To specify a page order, you can use the `nav_order` parameter in the front matter of the pages.
+
+#### Example
+
+```yaml
+---
+title: Customization
+nav_order: 6
+---
+```
+
+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[^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.
+
+{: .warning }
+The order of pages with equal `nav_order` parameters is unstable: it may change with each build.
+
+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.[^case-insensitive]
+
+Enclosing strings in quotation marks in front matter is optional, unless they contain "`[`", "`]`", "`{`", "`}`", "`,`", "`: `", or "` #`". Boolean, integer, and float values are treated as strings when enclosed in quotation marks.
+
+----
+
+[^floats]: Jekyll treats each integer *N* as equal to the corresponding float *N.0*. 
+
+[^case-insensitive]: *Note for users of previous versions of Just the Docs:* The option `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. 
diff --git a/docs/navigation/main/x.md b/docs/navigation/main/x.md
new file mode 100644
index 0000000000..264cbfffc4
--- /dev/null
+++ b/docs/navigation/main/x.md
@@ -0,0 +1,10 @@
+---
+title: X
+parent: Ancestry
+---
+# X
+
+```yaml
+title: X
+parent: Ancestry
+```
diff --git a/docs/navigation/main/xs.md b/docs/navigation/main/xs.md
new file mode 100644
index 0000000000..5bcd6afbec
--- /dev/null
+++ b/docs/navigation/main/xs.md
@@ -0,0 +1,10 @@
+---
+title: S
+parent: X
+---
+# S
+
+```yaml
+title: S
+parent: X
+```
diff --git a/docs/navigation/main/xt.md b/docs/navigation/main/xt.md
new file mode 100644
index 0000000000..cef47136a5
--- /dev/null
+++ b/docs/navigation/main/xt.md
@@ -0,0 +1,12 @@
+---
+title: T
+parent: S
+grand_parent: X
+---
+# T
+
+```yaml
+title: T
+parent: S
+grand_parent: X
+```
diff --git a/docs/navigation/main/xu.md b/docs/navigation/main/xu.md
new file mode 100644
index 0000000000..07d7e50786
--- /dev/null
+++ b/docs/navigation/main/xu.md
@@ -0,0 +1,12 @@
+---
+title: U
+parent: T
+ancestor: X
+---
+# U
+
+```yaml
+title: U
+parent: T
+ancestor: X
+```
diff --git a/docs/navigation/main/y.md b/docs/navigation/main/y.md
new file mode 100644
index 0000000000..e37a8e7fc9
--- /dev/null
+++ b/docs/navigation/main/y.md
@@ -0,0 +1,10 @@
+---
+title: Y
+parent: Ancestry
+---
+# Y
+
+```yaml
+title: Y
+parent: Ancestry
+```
diff --git a/docs/navigation/main/ys.md b/docs/navigation/main/ys.md
new file mode 100644
index 0000000000..cbcc090540
--- /dev/null
+++ b/docs/navigation/main/ys.md
@@ -0,0 +1,10 @@
+---
+title: S
+parent: Y
+---
+# S
+
+```yaml
+title: S
+parent: Y
+```
diff --git a/docs/navigation/main/yt.md b/docs/navigation/main/yt.md
new file mode 100644
index 0000000000..4f684d2134
--- /dev/null
+++ b/docs/navigation/main/yt.md
@@ -0,0 +1,12 @@
+---
+title: T
+parent: S
+ancestor: Y
+---
+# T
+
+```yaml
+title: T
+parent: S
+ancestor: Y
+```
diff --git a/docs/navigation/main/yu.md b/docs/navigation/main/yu.md
new file mode 100644
index 0000000000..8608153e56
--- /dev/null
+++ b/docs/navigation/main/yu.md
@@ -0,0 +1,12 @@
+---
+title: U
+parent: T
+ancestor: Y
+---
+# U
+
+```yaml
+title: U
+parent: T
+ancestor: Y
+```
diff --git a/docs/navigation/parents.md b/docs/navigation/parents.md
new file mode 100644
index 0000000000..5f8c73f1a7
--- /dev/null
+++ b/docs/navigation/parents.md
@@ -0,0 +1,11 @@
+---
+title: Breadcrumbs
+parent: Navigation 
+nav_order: 3
+---
+
+# Breadcrumbs
+
+When using the default layout, all pages except top-level pages will automatically have a list of 'breadcrumbs' at the top, linking to the parent page and to any higher-level ancestors.
+
+The default layout does not provide an option to suppress the list of breadcrumbs. To do that, you would need to define a new layout, or override the file `_includes/components/breadcrumbs.html` (e.g., with an empty file).
diff --git a/docs/search.md b/docs/search.md
index f48ae45cc4..7d12004d22 100644
--- a/docs/search.md
+++ b/docs/search.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Search
 nav_order: 7
 ---
diff --git a/docs/ui-components/buttons.md b/docs/ui-components/buttons.md
index 61fb1a2ff4..aedeb2d33a 100644
--- a/docs/ui-components/buttons.md
+++ b/docs/ui-components/buttons.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Buttons
 parent: UI Components
 nav_order: 2
diff --git a/docs/ui-components/callouts.md b/docs/ui-components/callouts.md
index e0ea86f270..bb3f41bcf6 100644
--- a/docs/ui-components/callouts.md
+++ b/docs/ui-components/callouts.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Callouts
 parent: UI Components
 nav_order: 7
diff --git a/docs/ui-components/code.md b/docs/ui-components/code/index.md
similarity index 98%
rename from docs/ui-components/code.md
rename to docs/ui-components/code/index.md
index b55e36169a..d4a70e20b7 100644
--- a/docs/ui-components/code.md
+++ b/docs/ui-components/code/index.md
@@ -1,8 +1,6 @@
 ---
-layout: default
 title: Code
 parent: UI Components
-has_children: true
 nav_order: 6
 ---
 
@@ -58,7 +56,7 @@ var fun = function lang(l) {
 ```
 {% endhighlight %}
 
-Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/line-nos.md %}).
+Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/code/line-numbers.md %}).
 
 ---
 
diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/code/line-numbers.md
similarity index 96%
rename from docs/ui-components/line-nos.md
rename to docs/ui-components/code/line-numbers.md
index 6cab7a6a49..463234f440 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/code/line-numbers.md
@@ -1,15 +1,11 @@
 ---
-layout: default
-title: Code with line numbers
+title: Line Numbers
 parent: Code
-grand_parent: UI Components
-permalink: /docs/ui-components/code/line-numbers/
 ---
 
-# Code snippets with line numbers
+# Code Snippets with Line Numbers
 
 {: .warning }
-
 In prior versions of the docs, we provided "workarounds" to rendering issues arising from code snippets with line numbers. While these seemed to resolve visual layout issues, they did not resolve core issues with Jekyll generating invalid HTML. See [the detailed explanation](#detailed-error-explanation) for more information.
 
 The default settings for HTML compression are incompatible with the HTML
diff --git a/docs/ui-components/ui-components.md b/docs/ui-components/index.md
similarity index 79%
rename from docs/ui-components/ui-components.md
rename to docs/ui-components/index.md
index 7d75a694c4..225a78b4fb 100644
--- a/docs/ui-components/ui-components.md
+++ b/docs/ui-components/index.md
@@ -1,9 +1,6 @@
 ---
-layout: default
 title: UI Components
 nav_order: 3
-has_children: true
-permalink: /docs/ui-components
 ---
 
 # UI Components
diff --git a/docs/ui-components/labels.md b/docs/ui-components/labels.md
index 05f02d4428..3e260c0144 100644
--- a/docs/ui-components/labels.md
+++ b/docs/ui-components/labels.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Labels
 parent: UI Components
 nav_order: 3
diff --git a/docs/ui-components/lists.md b/docs/ui-components/lists.md
index 12492c84e9..162698a24e 100644
--- a/docs/ui-components/lists.md
+++ b/docs/ui-components/lists.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Lists
 parent: UI Components
 nav_order: 5
diff --git a/docs/ui-components/tables.md b/docs/ui-components/tables.md
index 36920ca1ea..10549a82ef 100644
--- a/docs/ui-components/tables.md
+++ b/docs/ui-components/tables.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Tables
 parent: UI Components
 nav_order: 4
diff --git a/docs/ui-components/typography.md b/docs/ui-components/typography.md
index e767bd2e04..0e04eb2ef1 100644
--- a/docs/ui-components/typography.md
+++ b/docs/ui-components/typography.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Typography
 parent: UI Components
 nav_order: 1
diff --git a/docs/utilities/color.md b/docs/utilities/color.md
index 0f375978af..8f288e55c1 100644
--- a/docs/utilities/color.md
+++ b/docs/utilities/color.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Color
 parent: Utilities
 ---
diff --git a/docs/utilities/utilities.md b/docs/utilities/index.md
similarity index 84%
rename from docs/utilities/utilities.md
rename to docs/utilities/index.md
index e18bfc84cc..5a3c2f5cb1 100644
--- a/docs/utilities/utilities.md
+++ b/docs/utilities/index.md
@@ -1,9 +1,6 @@
 ---
-layout: default
 title: Utilities
 nav_order: 4
-has_children: true
-permalink: docs/utilities
 ---
 
 # Utilities
diff --git a/docs/utilities/layout.md b/docs/utilities/layout.md
index 264d4c4db4..65d371e957 100644
--- a/docs/utilities/layout.md
+++ b/docs/utilities/layout.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Layout
 parent: Utilities
 ---
diff --git a/docs/utilities/responsive-modifiers.md b/docs/utilities/responsive-modifiers.md
index c732530ed7..f7f2329947 100644
--- a/docs/utilities/responsive-modifiers.md
+++ b/docs/utilities/responsive-modifiers.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Responsive Modifiers
 parent: Utilities
 ---
diff --git a/docs/utilities/typography.md b/docs/utilities/typography.md
index 65a9a03f34..2ef74a6181 100644
--- a/docs/utilities/typography.md
+++ b/docs/utilities/typography.md
@@ -1,5 +1,4 @@
 ---
-layout: default
 title: Typography
 parent: Utilities
 ---
diff --git a/index.md b/index.md
index 98c62f147d..c02e752e18 100644
--- a/index.md
+++ b/index.md
@@ -1,6 +1,6 @@
 ---
-layout: default
 title: Home
+layout: home
 nav_order: 1
 description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
 permalink: /