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/_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/_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 %}