From 6061dd27e1cbc5e43e764bef450ac560e14d4f18 Mon Sep 17 00:00:00 2001
From: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Date: Mon, 26 Sep 2022 02:48:49 +0200
Subject: [PATCH] Add custom include for TOC heading (#980)
Closes #961. Replays a previous attempt.
---
_includes/toc_heading_custom.html | 1 +
_layouts/default.html | 2 +-
docs/customization.md | 22 +++++++++++++++++++---
3 files changed, 21 insertions(+), 4 deletions(-)
create mode 100644 _includes/toc_heading_custom.html
diff --git a/_includes/toc_heading_custom.html b/_includes/toc_heading_custom.html
new file mode 100644
index 00000000..82a77005
--- /dev/null
+++ b/_includes/toc_heading_custom.html
@@ -0,0 +1 @@
+<h2 class="text-delta">Table of contents</h2>
diff --git a/_layouts/default.html b/_layouts/default.html
index 5acf1c93..6e95317e 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -159,7 +159,7 @@ layout: table_wrappers
{% if page.has_children == true and page.has_toc != false %}
<hr>
- <h2 class="text-delta">Table of contents</h2>
+ {% include toc_heading_custom.html %}
<ul>
{% for child in toc_list %}
<li>
diff --git a/docs/customization.md b/docs/customization.md
index 385b2e18..ec9be264 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -129,11 +129,27 @@ For example, if you'd like to add your own styles for printing a page, you could
## Override includes
-The site can be modified by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) provided by default in the theme.
+You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides.
-To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. Any content added to this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
+To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
-The following includes were made available to you:
+Just the Docs provides the following custom includes files:
+
+### Custom TOC Heading
+
+`_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]({{ site.baseurl }}{% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
+
+#### Example
+{: .no_toc }
+
+To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
+```html
+<h2 class="text-delta">Contents</h2>
+```
+
+The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} .
### Custom Footer
--
GitLab