Generate linked child topic summaries

This mimics the parent-topic-with-links behavior seen in the original
Puppet Bolt documentation site, linking to each child/sub-topic under
the parent, with a summary taken from that sub-topic's first paragraph.

Parent .md templates must include the child_topics.html to endable this
behavior

Assisted-by: Claude Opus 4.8
Signed-off-by: Chris Tessmer <chris.tessmer@onyxpoint.com>

Author: op-ct

_includes/child_topics.html

@@ -0,0 +1,92 @@
+{%- comment -%}
+  child_topics.html — auto-generates an overview page's "on this page" list of
+  sub-topics from the site nav list, so parent-with-link sections don't need a
+  hand-maintained list of their sub-topics in the page body.
+
+  Renders a `<ul>` of child topic links for an overview page whose nav entry
+  has both `link:` and `items:` (e.g., OpenBolt's "Plans").
+
+  For each child: title as a link + first paragraph of the child's rendered
+  content as a short description. Children that don't resolve to a doc in the
+  current collection (e.g., missing rake-generated reference pages) render as
+  a bare link with no description.
+
+  Data source: the entry for this page in `_data/nav/<page.nav>.yml`. The
+  matching `nav_base` (URL prefix) is looked up in `_data/nav_map.yml`.
+{%- endcomment -%}
+
+{%- assign nav_base = nil -%}
+{%- for entry in site.data.nav_map -%}
+  {%- if entry.nav_key == page.nav -%}
+    {%- assign nav_base = entry.base -%}
+    {%- break -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- assign page_subpath = page.url | remove_first: nav_base -%}
+
+{%- comment -%}
+  Find the nav entry for the current page. Only matches entries with `items:`,
+  so pages whose nav entry has `link:` but no children (leaf pages) render
+  nothing here.
+{%- endcomment -%}
+{%- assign current_section = nil -%}
+{%- for item in site.data.nav[page.nav] -%}
+  {%- if item.link == page_subpath and item.items -%}
+    {%- assign current_section = item -%}
+    {%- break -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- if current_section -%}
+<ul>
+  {%- for child in current_section.items -%}
+    {%- assign child_link_first_char = child.link | slice: 0 -%}
+    {%- if child_link_first_char == '/' -%}
+      {%- assign child_url = child.link -%}
+    {%- else -%}
+      {%- assign child_url = child.link | prepend: nav_base -%}
+    {%- endif -%}
+
+    {%- assign child_doc = nil -%}
+    {%- for doc in site[page.collection] -%}
+      {%- if doc.url == child_url -%}
+        {%- assign child_doc = doc -%}
+        {%- break -%}
+      {%- endif -%}
+    {%- endfor -%}
+
+    {%- comment -%}
+      Extract the child's first intro paragraph for the description.
+
+      Every child page begins with `# Heading` then a plain intro paragraph,
+      so splitting the rendered HTML on `<p>` skips the `<h1>` and lands on the
+      first real paragraph.
+
+      `child_doc.content` is piped through `markdownify` first because Jekyll
+      only guarantees it holds rendered HTML for docs that happen to be built
+      before this page; docs built afterward still hold raw Markdown. Running
+      `markdownify` normalizes both cases to HTML so the `<p>` split is
+      deterministic regardless of build order.
+    {%- endcomment -%}
+    {%- assign first_para = nil -%}
+    {%- if child_doc -%}
+      {%- assign child_html = child_doc.content | markdownify -%}
+      {%- assign after_first_p = child_html | split: '<p>' -%}
+      {%- if after_first_p.size > 1 -%}
+        {%- assign first_para = after_first_p[1] | split: '</p>' | first -%}
+      {%- endif -%}
+    {%- endif -%}
+
+    {%- comment -%}
+      Title and description share one `<p>` (separated by a `<br>`) so the theme's
+      `.vp-doc p { margin: 16px 0 }` doesn't stack two paragraph margins between
+      them, which would push the description well below the link.
+    {%- endcomment -%}
+  <li>
+    <p><a href="{{ child_url }}">{{ child.text }}</a>{% if first_para %}<br>
+    {{ first_para }}{% endif %}</p>
+  </li>
+  {%- endfor -%}
+</ul>
+{%- endif -%}

docs/_openbolt_5x/bolt_examples.md

@@ -19,3 +19,5 @@ blog](https://puppet.com/search/?query=bolt&page=1&configure%5BhitsPerPage%5D=20
 
 > **Note:** Do you have a real-world use case for Bolt that you'd like to share? Reach out to us in the #bolt
   channel on [Slack](https://slack.puppet.com).
+
+{% include child_topics.html %}

docs/_openbolt_5x/plans.md

@@ -10,3 +10,5 @@ to do complex task operations, such as running multiple tasks with one command,
 computing values for the input for a task, or running certain tasks based on
 results of another task. You write plans in the Puppet language. And like tasks,
 plans are packaged in modules and can be shared on the Forge.
+
+{% include child_topics.html %}

docs/_openbolt_5x/tasks.md

@@ -12,3 +12,5 @@ You can write tasks in any programming language that can run on the targets,
 such as Bash, Python, or Ruby. Tasks are packaged within modules, so you can
 reuse, download, and share tasks on the Forge. Task metadata describes the task,
 validates input, and controls how the task runner executes the task.
+
+{% include child_topics.html %}