From f399e8ce8586263235d6e5c32c2d99567f97323c Mon Sep 17 00:00:00 2001
From: James Carr <james.carr@digital.cabinet-office.gov.uk>
Date: Tue, 17 Feb 2026 11:17:04 +0000
Subject: [PATCH 1/5] add option to skip rendering child resources for tighter
 controls over ToC Layouts

---
 .../table_of_contents/helpers.rb              |  8 ++--
 spec/table_of_contents/helpers_spec.rb        | 40 +++++++++++++++++++
 2 files changed, 44 insertions(+), 4 deletions(-)

diff --git a/lib/govuk_tech_docs/table_of_contents/helpers.rb b/lib/govuk_tech_docs/table_of_contents/helpers.rb
index 60090703..f8d88123 100644
--- a/lib/govuk_tech_docs/table_of_contents/helpers.rb
+++ b/lib/govuk_tech_docs/table_of_contents/helpers.rb
@@ -35,12 +35,12 @@ def select_top_level_html_files(resources)
           .select { |r| r.path.end_with?(".html") && (r.parent.nil? || r.parent.url == "/") }
       end
 
-      def multi_page_table_of_contents(resources, current_page, config, current_page_html = nil)
+      def multi_page_table_of_contents(resources, current_page, config, current_page_html = nil, include_child_resources: true)
         resources = sort_resources_stably(
           select_top_level_html_files(resources),
         )
 
-        render_page_tree(resources, current_page, config, current_page_html)
+        render_page_tree(resources, current_page, config, current_page_html, include_child_resources:)
       end
 
       def list_items_from_headings(html, url: "", max_level: nil)
@@ -54,7 +54,7 @@ def list_items_from_headings(html, url: "", max_level: nil)
         HeadingTreeRenderer.new(tree, max_level:).html
       end
 
-      def render_page_tree(resources, current_page, config, current_page_html)
+      def render_page_tree(resources, current_page, config, current_page_html, include_child_resources: true)
         resources = sort_resources_stably(resources)
 
         output = "<ul>\n"
@@ -84,7 +84,7 @@ def render_page_tree(resources, current_page, config, current_page_html)
             end
 
           link_value = get_path_to_resource(config, resource, current_page)
-          if resource.children.any? && resource.url != home_url
+          if resource.children.any? && resource.url != home_url && include_child_resources
             output += %(<li><a href="#{link_value}"><span>#{resource.data.title}</span></a>\n)
             output += render_page_tree(resource.children, current_page, config, current_page_html)
             output += "</li>\n"
diff --git a/spec/table_of_contents/helpers_spec.rb b/spec/table_of_contents/helpers_spec.rb
index 195a95e1..a6bf552a 100644
--- a/spec/table_of_contents/helpers_spec.rb
+++ b/spec/table_of_contents/helpers_spec.rb
@@ -393,5 +393,45 @@ def is_a?(klass)
 
       expect(subject.multi_page_table_of_contents(resources, current_page, config, current_page_html).strip).to eq(expected_multi_page_table_of_contents.strip)
     end
+
+    it "builds a table of contents from a single page resource when include_child_resources is set to false" do
+      resources = []
+      resources[0] = FakeResource.new("/index.html", '<h1 id="heading-one">Parent heading one</h1><h2 id="heading-two">Parent heading two</h2>', 10, "Index")
+      resources[1] = FakeResource.new("/1/2/a.html", '<h1 id="heading-one">Child heading one</h1><h2 id="heading-two">Child heading two</h2>', 20, "Sub page A", resources[0])
+      resources[2] = FakeResource.new("/1/2/3/b.html", '<h1 id="heading-one">Second child heading one</h1><h2 id="heading-two">Second child heading two</h2>', 30, "Sub page A", resources[0])
+
+      resources[0].add_children [resources[1], resources[2]]
+
+      current_page = double("current_page",
+                            data: double("page_frontmatter", description: "The description.", title: "The Title"),
+                            url: "/index.html",
+                            path: "/index.html",
+                            metadata: { locals: {} })
+
+      current_page_html = '<h1 id="heading-one">Parent heading one</h1><h2 id="heading-two">Parent heading two</h2>'
+
+      config = {
+        http_prefix: "/",
+        tech_docs: {
+          max_toc_heading_level: 3,
+          multipage_nav: true,
+        },
+      }
+
+      expected_multi_page_table_of_contents = %(
+<ul>
+  <li>
+    <a href="/index.html"><span>Parent heading one</span></a>
+    <ul>
+      <li>
+        <a href="/index.html#heading-two"><span>Parent heading two</span></a>
+      </li>
+    </ul>
+  </li>
+</ul>
+      )
+
+      expect(subject.multi_page_table_of_contents(resources, current_page, config, current_page_html, include_child_resources: false).strip).to eq(expected_multi_page_table_of_contents.strip)
+    end
   end
 end

From e744a31c2d041cc625740f396c52464ee67aba22 Mon Sep 17 00:00:00 2001
From: James Carr <james.carr@digital.cabinet-office.gov.uk>
Date: Tue, 17 Feb 2026 16:35:47 +0000
Subject: [PATCH 2/5] update version for release

---
 CHANGELOG.md                   | 4 ++++
 lib/govuk_tech_docs/version.rb | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d479eb3..0fad7bee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 5.2.1
+
+- [Add option to not render child resources when creating a table of contents](https://github.com/alphagov/tech-docs-gem/pull/439/changes)
+
 ## 5.2.0
 
 ### New features
diff --git a/lib/govuk_tech_docs/version.rb b/lib/govuk_tech_docs/version.rb
index 2090a235..5cddba1c 100644
--- a/lib/govuk_tech_docs/version.rb
+++ b/lib/govuk_tech_docs/version.rb
@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "5.2.0".freeze
+  VERSION = "5.2.1".freeze
 end

From a08f4f546b9239a86735e0271bac30e569bd6d07 Mon Sep 17 00:00:00 2001
From: James Carr <james.carr@digital.cabinet-office.gov.uk>
Date: Wed, 4 Mar 2026 11:08:04 +0000
Subject: [PATCH 3/5] update the README.md

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/README.md b/README.md
index 9c0781b6..59d2b239 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,52 @@ This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), par
 
 We use `npm` to download the govuk-frontend package. To update to a new version, change the version in the [package.json file](package.json) and run `npm update`.
 
+## Use layouts to structure your Table of Contents
+
+You can use layouts to group pages and customise your Table of Contents (ToC).  To create a template create a new ruby file in the `source/layouts` directory, for example `source/layouts/live_support_layout.erb`.  You can apply the template by including it in the frontmatter block of your required pages, for example:
+
+```diff
+    ---
+    title: Live support rota
+    weight: 1
+    last_reviewed_on: 1970-01-01
+    review_in: 3 months
++   layout: live_support_layout 
+    ---
+```
+
+
+This gem has helper functions to render your ToC.  You should use:
+
+- `single_page_table_of_contents` to create a ToC from the headings on the current page
+- `multi_page_table_of_contents` to create a ToC for a group of pages, opened at the current page
+
+The `multi_page_table_of_contents`  helper function takes [an optional `include_child_resources`](https://github.com/alphagov/tech-docs-gem/pull/439) parameter to help with your custom ToC.  The default value of `include_child_resources` is `true`.
+
+Below is an example of using the helper functions in a custom layout:
+
+```
+<%
+wrap_layout :core do
+
+  content_for(:toc_module, "in-page-navigation")
+
+  use_multipage_nav = current_page.data.fetch(:multipage_nav, config[:tech_docs][:multipage_nav])
+
+  content_for :sidebar do
+    if use_multipage_nav %>
+      <%= multi_page_table_of_contents(sitemap.resources, current_page, config, yield) %>
+    <% else %>
+      <%= single_page_table_of_contents(yield, max_level: config[:tech_docs][:max_toc_heading_level]) %>
+    <% end %>
+  <%
+  end
+
+  html
+end
+%>
+```
+
 ## Developing locally
 
 There are 2 ways to develop with this gem. You can see your changes on either:

From b3a9e3e116dade62185d356423fe2d7186476f73 Mon Sep 17 00:00:00 2001
From: James Carr <james.carr@digital.cabinet-office.gov.uk>
Date: Wed, 4 Mar 2026 11:12:35 +0000
Subject: [PATCH 4/5] update the README.md

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 59d2b239..19cd3970 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,7 @@ wrap_layout :core do
 
   content_for :sidebar do
     if use_multipage_nav %>
-      <%= multi_page_table_of_contents(sitemap.resources, current_page, config, yield) %>
+      <%= multi_page_table_of_contents(sitemap.resources[1], current_page, config, yield, include_child_resources: false) %>
     <% else %>
       <%= single_page_table_of_contents(yield, max_level: config[:tech_docs][:max_toc_heading_level]) %>
     <% end %>

From dac5a120065215a9e24f466c0b558bdcea729c05 Mon Sep 17 00:00:00 2001
From: James Carr <james.carr@digital.cabinet-office.gov.uk>
Date: Wed, 4 Mar 2026 14:03:05 +0000
Subject: [PATCH 5/5] make the readme content more readmen appropriate

---
 README.md | 63 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 36 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 19cd3970..6d52b425 100644
--- a/README.md
+++ b/README.md
@@ -17,51 +17,60 @@ This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), par
 
 We use `npm` to download the govuk-frontend package. To update to a new version, change the version in the [package.json file](package.json) and run `npm update`.
 
-## Use layouts to structure your Table of Contents
-
-You can use layouts to group pages and customise your Table of Contents (ToC).  To create a template create a new ruby file in the `source/layouts` directory, for example `source/layouts/live_support_layout.erb`.  You can apply the template by including it in the frontmatter block of your required pages, for example:
-
-```diff
-    ---
-    title: Live support rota
-    weight: 1
-    last_reviewed_on: 1970-01-01
-    review_in: 3 months
-+   layout: live_support_layout 
-    ---
-```
-
+## Table of contents helper functions
 
-This gem has helper functions to render your ToC.  You should use:
+With `Middleman` you can apply layouts to group pages and customise sites. This gem has the following additional helper functions to manage the table of contents (ToC):
 
 - `single_page_table_of_contents` to create a ToC from the headings on the current page
 - `multi_page_table_of_contents` to create a ToC for a group of pages, opened at the current page
 
-The `multi_page_table_of_contents`  helper function takes [an optional `include_child_resources`](https://github.com/alphagov/tech-docs-gem/pull/439) parameter to help with your custom ToC.  The default value of `include_child_resources` is `true`.
+### Single page table of contents
+
+The `single_page_table_of_contents` helper has the following parameters:
+
+| Parameter   | Description                                                                            | 
+|-------------|----------------------------------------------------------------------------------------|
+| `html`      | The html of the current page.                                                          | 
+| `url`       | Optional parameter used to override the url of the page heading. Defaults to `""`.     | 
+| `max_level` | Optional parameter used to set the depth of the table of contents.  Defaults to `nil`. |  
 
-Below is an example of using the helper functions in a custom layout:
+Below is an example of using `single_page_table_of_contents` in a layout file:
 
 ```
 <%
 wrap_layout :core do
+  content_for :sidebar do
+      <%= single_page_table_of_contents(html, max_level: 2) %>
+  end
+end
+%>
+```
+
+This example will create a ToC containing the current page title, and nested headings to a depth of 2. 
 
-  content_for(:toc_module, "in-page-navigation")
+### Multi page table of contents
 
-  use_multipage_nav = current_page.data.fetch(:multipage_nav, config[:tech_docs][:multipage_nav])
+The `multi_page_table_of_contents`  has the following parameters:
 
+| Parameter                 | Description                                                                                                                                                         |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `resources`               | An array of middleman site resources for the pages to be included in the ToC.                                                                                       |
+| `current_page`            | The resource object found in the [middleman current_page](https://www.rubydoc.info/gems/middleman-core/Middleman/TemplateContext#current_resource-instance_method). |
+| `config`                  | Site settings defined in `/config/tech-docs.yaml`.                                                                                                                  |
+| `current_page_html`       | Optional html of the current page.  Defaults to `nil`.                                                                                                              |
+| `include_child_resources` | Optional setting used to include child resources when creating a ToC.  Defaults to `true`.                                                                          |
+Below is an example of using `multi_page_table_of_contents` in a layout file:
+
+```
+<%
+wrap_layout :core do
   content_for :sidebar do
-    if use_multipage_nav %>
-      <%= multi_page_table_of_contents(sitemap.resources[1], current_page, config, yield, include_child_resources: false) %>
-    <% else %>
-      <%= single_page_table_of_contents(yield, max_level: config[:tech_docs][:max_toc_heading_level]) %>
-    <% end %>
-  <%
+      <%= multi_page_table_of_contents(sitemap.resources, current_page, config, yield, include_child_resources: true) %>
   end
-
-  html
 end
 %>
 ```
+This example will create a ToC containing the page title of each resource, as a heading.  Each heading can be expanded to show nested headings to the depth defined in the site config.  If `include_child_resources` is set to `true`, child resources will also be included.
 
 ## Developing locally