From 589fd6e087023e7bf274052978af37610433c3e1 Mon Sep 17 00:00:00 2001 From: Chris Tessmer Date: Wed, 1 Jul 2026 20:53:02 +0000 Subject: [PATCH 1/4] Support nav item parents that are links (openbolt) 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 --- _includes/nav-item.html | 54 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/_includes/nav-item.html b/_includes/nav-item.html index 8d5cd1347..5c4332c64 100644 --- a/_includes/nav-item.html +++ b/_includes/nav-item.html @@ -1,22 +1,68 @@ +{%- comment -%} + This file renders a single sidebar nav item, which is a list element defined + in `_data/nav/.yml`. + + The nav item is passed in as `include.item` and can take one of three shapes: + + - `items:` only -> collapsible topic header (just expands/collapses) + - `link:` only -> leaf item; display link to page content + - `link:` and `items:` -> collapsible header AND has its own page content + (e.g., OpenBolt's "Plans") + + Nested levels are handled by recursing into `include.item.items`. +{%- endcomment -%} {% if include.item.items %} {% assign nav_next_level = include.level | plus: 1 %} + {%- comment -%} + It's necessary to pre-render all child items before this item, + because we'll need to peek at their formatting to decide our own. + {%- endcomment -%} {% capture nav_children %} {% for child in include.item.items %} {% include nav-item.html item=child level=nav_next_level %} {% endfor %} {% endcapture %} + {%- comment -%} + Compute our item's absolute URL/`nav_item_url`: + - Absolute links ("/openvox-server/latest/http_api_index.html") used as-is + - Relative links ("plans.html") prepend `nav_base` ("/openbolt/latest/") + + It's important to compute this AFTER the recursive children capture above: + Liquid's `assign` (below) leaks between includes + theirs would whack ours! + {%- endcomment -%} + {% if include.item.link %} + {% assign nav_link_first_char = include.item.link | slice: 0 %} + {% if nav_link_first_char == '/' %} + {% assign nav_item_url = include.item.link %} + {% else %} + {% assign nav_item_url = include.item.link | prepend: nav_base %} + {% endif %} + {% endif %} + + {%- comment -%} + Peek at buffered markup; if any are `is-active`, our formatting must change + {%- endcomment -%} {% assign nav_has_active = false %} {% if nav_children contains 'is-active' %} {% assign nav_has_active = true %} {% endif %} + {% if include.item.link and nav_item_url == page.url %} + {% assign nav_has_active = true %} + {% endif %}
-
+
-

{{ include.item.text }}

+ {% if include.item.link %} + +

{{ include.item.text }}

+ + {% else %} +

{{ include.item.text }}

+ {% endif %}
@@ -28,10 +74,6 @@

{{ include.item.text }}

{% elsif include.item.link %} - {%- comment -%} - Links starting with '/' are already absolute site paths. Prepending nav_base (which also - starts with '/') would produce a broken double-prefix like /openvox/latest//other/page.html. - {%- endcomment -%} {% assign nav_link_first_char = include.item.link | slice: 0 %} {% if nav_link_first_char == '/' %} {% assign nav_item_url = include.item.link %} From 391491f1f5fc4eb604811eb098de752b9e4cf225 Mon Sep 17 00:00:00 2001 From: Chris Tessmer Date: Wed, 1 Jul 2026 21:51:02 +0000 Subject: [PATCH 2/4] Re-brand navbar, landing, and version pages - 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 --- _data/nav/openbolt_5x.yml | 38 +++++++-------- docs/_openbolt_5x/bolt.md | 72 ---------------------------- docs/_openbolt_5x/bolt_versioning.md | 18 +++---- docs/_openbolt_5x/index.md | 61 +++++++++++++++++++---- 4 files changed, 81 insertions(+), 108 deletions(-) delete mode 100644 docs/_openbolt_5x/bolt.md diff --git a/_data/nav/openbolt_5x.yml b/_data/nav/openbolt_5x.yml index e98bcfbe5..69a551cb8 100644 --- a/_data/nav/openbolt_5x.yml +++ b/_data/nav/openbolt_5x.yml @@ -1,42 +1,42 @@ --- -- text: Welcome to Puppet Bolt® - link: bolt.html +- text: Welcome to OpenBolt + link: index.html items: - text: Developer updates link: developer_updates.html - text: Release notes link: release_notes.html - - text: Bolt versioning + - text: OpenBolt versioning link: bolt_versioning.html - text: Known issues link: bolt_known_issues.html -- text: Installing Bolt +- text: Installing OpenBolt items: - - text: Installing Bolt + - text: Installing OpenBolt link: bolt_installing.html - - text: Run Bolt from a Docker image + - text: Run from a Docker image link: running_bolt_in_docker.html -- text: Getting started with Bolt +- text: Getting started with OpenBolt link: getting_started_with_bolt.html -- text: Configuring Bolt +- text: Configuring OpenBolt items: - text: Bolt projects link: projects.html - text: Inventory files link: inventory_files.html - - text: Configuring Bolt + - text: Configuring OpenBolt link: configuring_bolt.html - text: Logs link: logs.html - - text: Escalating privilege with Bolt + - text: Escalating privilege link: privilege_escalation.html - - text: Setting up VS Code for Bolt + - text: VS Code and OpenBolt link: vscode_and_bolt.html -- text: Running Bolt +- text: Running OpenBolt items: - - text: Run Bolt + - text: Run OpenBolt link: running_bolt_commands.html - - text: Run Bolt on network devices + - text: Run OpenBolt on network devices link: running_bolt_network.html - text: Scripts items: @@ -88,20 +88,20 @@ link: supported_plugins.html - text: Writing plugins link: writing_plugins.html -- text: Using Bolt with Puppet +- text: Using OpenBolt with Puppet/OpenVox items: - text: Applying Puppet code link: applying_manifest_blocks.html - - text: Using Bolt with Hiera + - text: Using OpenBolt with Hiera link: hiera.html - - text: Connecting Bolt to PuppetDB + - text: Connecting OpenBolt to PuppetDB link: bolt_connect_puppetdb.html -- text: Bolt Examples +- text: OpenBolt Examples link: bolt_examples.html items: - text: Automating Windows targets link: automating_windows_targets.html - - text: Deploy a TIG stack with Bolt + - text: Deploy a TIG stack with OpenBolt link: tig_stack.html - text: "\U0001F9EA Experimental features" link: experimental_features.html diff --git a/docs/_openbolt_5x/bolt.md b/docs/_openbolt_5x/bolt.md deleted file mode 100644 index bb8235179..000000000 --- a/docs/_openbolt_5x/bolt.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: default -title: Welcome to Puppet Bolt® ---- - -# Welcome to Puppet Bolt® - -Bolt is an open source orchestration tool that automates the manual work it -takes to maintain your infrastructure. Use Bolt to automate tasks that you -perform on an as-needed basis or as part of a greater orchestration workflow. -For example, you can use Bolt to patch and update systems, troubleshoot servers, -deploy applications, or stop and restart services. Bolt can be installed on your -local workstation and connects directly to remote targets with SSH or WinRM, so -you are not required to install any agent software. - -![Puppet Bolt logo](bolt-logo-dark.png) - -## Helpful Bolt docs links - -### Install Bolt - -- [Installing Bolt](bolt_installing.html) - Follow the installation instructions for your operating system: \*nix, macOS, or Windows. - -### Make one-time changes to your remote targets - -- [Run a command](running_bolt_commands.html) -- [Run a script](running_bolt_commands.html) -- [Upload files](running_bolt_commands.html) - -### Automate your workflow with existing tasks and plans - -- [Running tasks](bolt_running_tasks.html) -- [Running plans](bolt_running_plans.html) - -### Create your own tasks and plans - -- [Writing tasks](writing_tasks.html) -- [Writing plans in Puppet® language](writing_plans.html) -- [Writing plans in YAML](writing_yaml_plans.html) -- [Example plans](writing_plans.html) -- [Applying manifest blocks](applying_manifest_blocks.html) - -## Other useful places - -### Learn the basics - -- [Getting started with Bolt](getting_started_with_bolt.html) -- [Bolt examples](bolt_examples.html) - Guided examples of how Bolt can help you automate common tasks. -- [Bolt example repo](https://github.com/puppetlabs/bolt-examples) - A curated repo of common Bolt patterns that you can use to reference syntax and structure. - -### Watch Bolt development - -- [Bolt project on GitHub](https://github.com/puppetlabs/bolt) - -### Docs for related Puppet products - -- [Open source Puppet](/openvox/latest/index.html) -- [Puppet Development Kit](/pdk.html) - -### Why and how people are using Bolt - -- [Product Spotlight Webinar: Puppet Tasks](https://puppet.com/resources/webinar/product-spotlight-webinar-puppet-taskstm) -- [Combining PowerShell, Bolt and Puppet Tasks](https://puppet.com/blog/combining-powershell-bolt-and-puppet-tasks-part-1) -- [Automating from zero to something](https://puppet.com/blog/automating-from-zero-to-something/) - -### Share and contribute - -- [Join us on Slack](https://slack.puppet.com) - Join the #bolt channel. -- [Follow us on Twitter](https://twitter.com/puppetize/) -- [Engage with the Puppet community](https://puppet.com/community) - Share what you know and get help from other users and employees. -- [Puppet Forge](https://forge.puppet.com) - Find modules you can use, and contribute modules you've made to the community. -- [Open source projects from Puppet on GitHub](https://github.com/puppetlabs/) diff --git a/docs/_openbolt_5x/bolt_versioning.md b/docs/_openbolt_5x/bolt_versioning.md index 6f6e4b7e2..6b19671b8 100644 --- a/docs/_openbolt_5x/bolt_versioning.md +++ b/docs/_openbolt_5x/bolt_versioning.md @@ -1,23 +1,23 @@ --- layout: default -title: Bolt versioning +title: OpenBolt versioning --- -# Bolt versioning +# OpenBolt versioning -Bolt follows [semantic versioning](https://semver.org/) guidelines. +OpenBolt follows [semantic versioning](https://semver.org/) guidelines. This system uses an "x.y.z" pattern, where "x" is the number of a major release, "y" indicates a minor release that introduces new features but does not include breaking changes, and "z" reflects a bug fix release. -## Bolt API +## OpenBolt API -The 2.0 series of Bolt is stable and will be free of breaking changes to its +The 5.0 series of OpenBolt is stable and will be free of breaking changes to its public API. In general this means that plans, inventory and config tested with -any 2.y series release of Bolt will continue to work when used with a later 2.y -series release. You can expect the following types of changes in the 2.0 series: +any 5.y series release of OpenBolt will continue to work when used with a later 5.y +series release. You can expect the following types of changes in the 5.0 series: - New keys in JSON format output. - Differences in log output and human format output. @@ -27,8 +27,8 @@ series release. You can expect the following types of changes in the 2.0 series: - Versions of bundled modules will be updated and might include breaking changes. -## Bolt releases +## OpenBolt releases -For the 2.y series of Bolt we do not plan to backport bug fixes to any +For the 5.y series of OpenBolt we do not plan to backport bug fixes to any previously released version. You are encouraged to upgrade frequently and use the latest release. diff --git a/docs/_openbolt_5x/index.md b/docs/_openbolt_5x/index.md index ab1941655..fb65cef7c 100644 --- a/docs/_openbolt_5x/index.md +++ b/docs/_openbolt_5x/index.md @@ -1,12 +1,12 @@ --- layout: default -title: OpenBolt 5 +title: Welcome to OpenBolt 5 --- -OpenBolt is a community implementation of [Puppet Bolt](https://github.com/puppetlabs/bolt) — an open -source orchestration tool that automates infrastructure management over SSH and WinRM without requiring -agents. Use OpenBolt to run commands, scripts, and tasks across remote targets, or to orchestrate -complex workflows using plans. +OpenBolt is an open source community implementation of [Puppet Bolt](https://github.com/puppetlabs/bolt) +— an orchestration tool that automates infrastructure management over SSH and WinRM without requiring +product-specific agents. Use OpenBolt to run commands, scripts, and tasks across +remote targets, or to orchestrate complex workflows using plans. OpenBolt is downstream-compatible with Puppet Bolt — existing tasks, plans, modules, and inventory files work unchanged. @@ -20,12 +20,57 @@ Work is expressed at several levels: - **Commands** — run a shell command directly on targets - **Scripts** — upload and execute a script file on targets -- **Tasks** — self-contained, reusable units of automation with defined parameters; written in any language -- **Plans** — Puppet or YAML programs that sequence tasks, commands, and scripts across multiple targets with conditional logic +- **[Tasks](tasks.html)** — self-contained, reusable units of automation with defined parameters; written in any language +- **[Plans](plans.html)** — Puppet or YAML programs that sequence tasks, commands, and scripts across multiple targets with conditional logic -## Getting started +## Helpful OpenBolt docs links +### Install OpenBolt + +- [Installing OpenBolt](bolt_installing.html) - Follow the installation instructions for your operating system: \*nix, macOS, or Windows. +### Make one-time changes to your remote targets + +- [Run a command](running_bolt_commands.html#run-a-command) +- [Run a script](running_bolt_commands.html#run-a-script) +- [Upload files](running_bolt_commands.html#upload-a-file-or-directory) + +### Automate your workflow with existing tasks and plans + +- [Running tasks](bolt_running_tasks.html) +- [Running plans](bolt_running_plans.html) + +### Create your own tasks and plans - [Installing OpenBolt](bolt_installing.html) - [Getting started with Bolt](getting_started_with_bolt.html) - [Writing tasks](writing_tasks.html) - [Writing plans](writing_plans.html) +- [Writing plans in YAML](writing_yaml_plans.html) +- [Example plans](writing_plans.html) +- [Applying manifest blocks](applying_manifest_blocks.html) + +## Other useful places + +### Learn the basics + +- [Getting started with OpenBolt](getting_started_with_bolt.html) +- [OpenBolt examples](bolt_examples.html) - Guided examples of how OpenBolt can help you automate common tasks. + +### Watch OpenBolt development + +- [OpenBolt project on GitHub](https://github.com/OpenVoxProject/openbolt) + +### Docs for related OpenVox products + +- [OpenVox](/openvox/latest/) – open source, community-maintained implementation of Puppet +- [OpenVox Server](/openvox-server/latest/) +- [OpenVoxDB](/openvoxdb/latest/) + + +### Share and contribute + +- [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/) +- [Open source projects from VoxPupuli on GitHub](https://github.com/voxpupuli/) +- [Puppet Forge](https://forge.puppet.com) - Find modules you can use, and contribute modules you've made to the community. From 3cea98f927902cf17fa56204bc8705a66e6ee348 Mon Sep 17 00:00:00 2001 From: Chris Tessmer Date: Wed, 1 Jul 2026 21:41:43 -0400 Subject: [PATCH 3/4] 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 --- _includes/child_topics.html | 92 ++++++++++++++++++++++++++++++ docs/_openbolt_5x/bolt_examples.md | 2 + docs/_openbolt_5x/plans.md | 2 + docs/_openbolt_5x/tasks.md | 2 + 4 files changed, 98 insertions(+) create mode 100644 _includes/child_topics.html diff --git a/_includes/child_topics.html b/_includes/child_topics.html new file mode 100644 index 000000000..1e1373597 --- /dev/null +++ b/_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 `
    ` 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/.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 -%} +
      + {%- 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 `

      ` skips the `

      ` 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 `

      ` 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: '

      ' -%} + {%- if after_first_p.size > 1 -%} + {%- assign first_para = after_first_p[1] | split: '

      ' | first -%} + {%- endif -%} + {%- endif -%} + + {%- comment -%} + Title and description share one `

      ` (separated by a `
      `) 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 -%} +

    • +

      {{ child.text }}{% if first_para %}
      + {{ first_para }}{% endif %}

      +
      • + {%- endfor -%} +

    +{%- endif -%} diff --git a/docs/_openbolt_5x/bolt_examples.md b/docs/_openbolt_5x/bolt_examples.md index baeacda68..c182ea483 100644 --- a/docs/_openbolt_5x/bolt_examples.md +++ b/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 %} diff --git a/docs/_openbolt_5x/plans.md b/docs/_openbolt_5x/plans.md index d336cca8a..65da8cb82 100644 --- a/docs/_openbolt_5x/plans.md +++ b/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 %} diff --git a/docs/_openbolt_5x/tasks.md b/docs/_openbolt_5x/tasks.md index 6915be9d5..cf12bc7fc 100644 --- a/docs/_openbolt_5x/tasks.md +++ b/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 %} From fb1fb6029dff4109b31317e2f9652a3e895b27ce Mon Sep 17 00:00:00 2001 From: Chris Tessmer Date: Thu, 2 Jul 2026 15:02:22 +0000 Subject: [PATCH 4/4] Fix markdown lint Signed-off-by: Chris Tessmer --- docs/_openbolt_5x/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/_openbolt_5x/index.md b/docs/_openbolt_5x/index.md index fb65cef7c..63a38b196 100644 --- a/docs/_openbolt_5x/index.md +++ b/docs/_openbolt_5x/index.md @@ -28,6 +28,7 @@ Work is expressed at several levels: ### Install OpenBolt - [Installing OpenBolt](bolt_installing.html) - Follow the installation instructions for your operating system: \*nix, macOS, or Windows. + ### Make one-time changes to your remote targets - [Run a command](running_bolt_commands.html#run-a-command) @@ -40,6 +41,7 @@ Work is expressed at several levels: - [Running plans](bolt_running_plans.html) ### Create your own tasks and plans + - [Installing OpenBolt](bolt_installing.html) - [Getting started with Bolt](getting_started_with_bolt.html) - [Writing tasks](writing_tasks.html) @@ -70,7 +72,7 @@ Work is expressed at several levels: - [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/) +- [Connect with the OpenVox/VoxPupuli Community](https://voxpupuli.org/connect/) - [OpenVox on GitHub](https://github.com/openvox/) - [Open source projects from VoxPupuli on GitHub](https://github.com/voxpupuli/) - [Puppet Forge](https://forge.puppet.com) - Find modules you can use, and contribute modules you've made to the community.