Fix/missing openbolt topic links and subtopic summaries by op-ct · Pull Request #387 · OpenVoxProject/openvox-docs

op-ct · 2026-07-02T02:37:57Z

This patch restores the behavior and missing content of the original Bolt documentation site:

Un-hides the missing topic pages (bolt, plans, tasks, bolt_examples) in the navbar
- Fix: Correctly handle item: + link: items in the _data/nav/<product>_<version>.yml data
- (The data for this was already present, but is ignored by the current template logic)
Restores the missing (automatically-generated) sub-topic summaries in the now-unhidden topic pages
Fixes the content of the un-hidden pages and nav bar items:
- Changes branding to OpenBolt/OpenVox instead of Bolt/Puppet (was especially irksome in the nav bar)
- Removes the now-unhidden bolt page (the original Puppet Bolt landing page, left in the repo)
- Adapts relevant copy from the now-removed bolt page into index (the OpenBolt landing page)

This fix is a prerequisite to replacing the defunct pup.pt links, referenced in bolt's error and help messages.

Implementation notes:

The shared navbar code in _includes/nav-item.html is designed (and tested) to not affect the behavior of any nav item that doesn't contain both item: and link:
The topic summaries are generated by the new template _includes/child_topics.html. This is an opt-in template, called directly by the topic pages (example from plan.md).
- These are necessary to present landing pages as intended as links in bolt's error and help messages.

Assisted-by: Claude Opus 4.7 & 4.8
Fixes #386

Checklist

I have:

read the CONTRIBUTING.md document
read and accepted the Developer Certificate of Origin document and added a Signed-off-by annotation to each of my commits
read and accepted the AI Policy document and added Generated-by or Assisted-by annotations to each of my commits created with the help of an AI agent
tested this code
included documentation (including possible behaviour changes)
documented the code
added or modified regression test(s)
added or modified unit test(s)

miharp · 2026-07-02T10:26:17Z

I put together an alternative approach, #388, there are some minor tradeoffs but it seems simpler and less brittle.

binford2k · 2026-07-02T15:53:32Z

this PR commingles several topics. I'd like to see them as individual PRs

binford2k · 2026-07-02T15:55:55Z

+    {%- endfor -%}
+
+    {%- comment -%}
+      Extract the child's first intro paragraph for the description.


I think I'd rather that we populate the front matter description field.

Fwiw, the example you linked doesn't autogenerate descriptions. See "running plans" on https://help.puppet.com/bolt/current/topics/plans.htm

op-ct · 2026-07-02T16:05:13Z

I put together an alternative approach, #388, there are some minor tradeoffs but it seems simpler and less brittle.

~~I don't see #388 as an alternative approach; it only adds simple "overview" links and doesn't address the buried data or follow-on issues with the pages that are now exposed.~~ Edit: I see you've added an alt child page approach now 👍

this PR commingles several topics. I'd like to see them as individual PRs

I'd considered that, but ended up staging them as individual commits in a single PR, because each one basically fixes a follow-on issue the previous fix exposed, and I didn't want merging just one PR in the chain to result in publishing not-actually-fixed docs.

Is that a legitimate concern? If not, I'll happily break it up into individual PRs.

The OpenBolt page renders missed the top-level landing pages for plans and tasks (and the product itself) because they didn't handle the case where a nav item parent ALSO contained a link to their own content. This patch adds that capability to the liquid templates, along with some comments to avoid gotchas Assisted-by: Claude Opus 4.7 Signed-off-by: Chris Tessmer <chris.tessmer@onyxpoint.com>

- Remove old bolt.html (now reachable by nav menu template fix) - Recover/adapt relevant 'bolt.html' page content into index page - Rebrand Bolt to OpenBolt on navbar, landing, and version pages - Fix various broken cross-links This is not a complete overhaul for branding and correctness, but it fixes what I needed to update before removing 'bolt.html' Signed-off-by: Chris Tessmer <chris.tessmer@onyxpoint.com>

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>

Signed-off-by: Chris Tessmer <chris.tessmer@onyxpoint.com>

miharp

Built the branch locally and tested both URL prefixes. The nav-item change checks out — no rendering change for any other collection's nav shapes. One functional issue with the new child_topics include on the versioned /openbolt/5.x/ pages, plus three small content fixes on index.md; all four have one-click suggestions inline.

miharp · 2026-07-03T10:37:29Z

+{%- 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 -%}


The child-topics list only renders under /openbolt/latest/. Each collection also publishes at its versioned prefix (/openbolt/5.x/, via the _openbolt_latest symlink), but nav_map has a single base: /openbolt/latest/ for this nav key, so on a 5.x page remove_first: nav_base strips nothing, no nav entry matches, and the include silently emits nothing. Deriving the base from the page's own URL (same technique as sidebar.html) works under both prefixes, and won't need nav_map bookkeeping when 6.x lands:

Suggested change

{%- 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 -%}

{%- assign nav_collection_dir = page.collection | prepend: '_' | append: '/' -%}

{%- assign page_subpath = page.relative_path | remove_first: nav_collection_dir | replace: '.md', '.html' | replace: '.markdown', '.html' -%}

{%- assign nav_base = page.url | remove: page_subpath -%}

Tested locally: with this, /openbolt/5.x/plans.html renders the full list with version-correct child links (descriptions too, since the site[page.collection] lookup then matches), and /openbolt/latest/ renders exactly as before.

miharp · 2026-07-03T10:39:59Z

+- [Join us on Slack](https://voxpupuli.slack.com/) - Join the #bolt channel.
+- Follow us on [Bluesky](https://bsky.app/profile/voxpupuli.bsky.social/) or [Mastodon](https://fosstodon.org/@voxpupuli/)
+- [Connect with the OpenVox/VoxPupuli Community](https://voxpupuli.org/connect/)
+- [OpenVox on GitHub](https://github.com/openvox/)


github.com/openvox is an unrelated company (OpenVox Communication Co., Ltd., a telephony hardware vendor) that happens to own that org name — and since it returns a 200 rather than a 404, link checkers won't catch it. The project org is OpenVoxProject, as used elsewhere in this file:

Suggested change

- [OpenVox on GitHub](https://github.com/openvox/)

- [OpenVox on GitHub](https://github.com/OpenVoxProject/)

miharp · 2026-07-03T10:45:07Z

 - [Installing OpenBolt](bolt_installing.html)
 - [Getting started with Bolt](getting_started_with_bolt.html)


I think these two are leftovers from the old bolt.md "Getting started" list — both already appear on this page under better homes: "Installing OpenBolt" under Install OpenBolt (line 30) and the getting-started page under Learn the basics (line 57, where it's labeled "Getting started with OpenBolt" — this copy still says "Bolt"). Dropping them removes the duplication and the naming mismatch in one go:

Suggested change

- [Installing OpenBolt](bolt_installing.html)

- [Getting started with Bolt](getting_started_with_bolt.html)

miharp · 2026-07-03T10:46:21Z

 - [Writing tasks](writing_tasks.html)
 - [Writing plans](writing_plans.html)
+- [Writing plans in YAML](writing_yaml_plans.html)
+- [Example plans](writing_plans.html)


"Example plans" points at the same writing_plans.html as the "Writing plans" bullet two lines up, and no dedicated example-plans page exists (carried over from the old bolt.md). Since Learn the basics already links "OpenBolt examples" (bolt_examples.html), the cleanest fix is to drop the bullet:

Suggested change

- [Example plans](writing_plans.html)

op-ct requested a review from a team as a code owner July 2, 2026 02:37

miharp mentioned this pull request Jul 2, 2026

Alternative fix: make OpenBolt topic-group pages reachable from the navbar #388

Closed

binford2k requested changes Jul 2, 2026

View reviewed changes

op-ct added 4 commits July 2, 2026 17:03

Fix markdown lint

fb1fb60

Signed-off-by: Chris Tessmer <chris.tessmer@onyxpoint.com>

op-ct force-pushed the fix/missing-openbolt-topic-links-and-subtopic-summaries branch from a182c48 to fb1fb60 Compare July 2, 2026 17:03

miharp reviewed Jul 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix/missing openbolt topic links and subtopic summaries#387

Fix/missing openbolt topic links and subtopic summaries#387
op-ct wants to merge 4 commits into
OpenVoxProject:masterfrom
op-ct:fix/missing-openbolt-topic-links-and-subtopic-summaries

op-ct commented Jul 2, 2026 •

edited

Loading

Uh oh!

miharp commented Jul 2, 2026

Uh oh!

binford2k commented Jul 2, 2026

Uh oh!

binford2k Jul 2, 2026

Uh oh!

op-ct commented Jul 2, 2026 •

edited

Loading

Uh oh!

miharp left a comment

Uh oh!

miharp Jul 3, 2026

Uh oh!

miharp Jul 3, 2026

Uh oh!

miharp Jul 3, 2026

Uh oh!

miharp Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- [OpenVox on GitHub](https://github.com/openvox/)
	- [OpenVox on GitHub](https://github.com/OpenVoxProject/)

		- [Installing OpenBolt](bolt_installing.html)
		- [Getting started with Bolt](getting_started_with_bolt.html)

Uh oh!

Conversation

op-ct commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

miharp commented Jul 2, 2026

Uh oh!

binford2k commented Jul 2, 2026

Uh oh!

binford2k Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

op-ct commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miharp left a comment

Choose a reason for hiding this comment

Uh oh!

miharp Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

miharp Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

miharp Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

miharp Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

op-ct commented Jul 2, 2026 •

edited

Loading

op-ct commented Jul 2, 2026 •

edited

Loading