Move static docs to openvox-docs, remove DITA#233
Open
miharp wants to merge 2 commits into
Open
Conversation
miharp
changed the title
miharp
force-pushed
the
jekyll-docs
branch
2 times, most recently
from
068fe90 to
8947949
Compare
jay7x
approved these changes
May 12, 2026
Comment on lines
+132
to
+147
| run: | | ||
| # Every ERB template must have a generated page in the output | ||
| for template in documentation/templates/*.md.erb; do | ||
| page="documentation/jekyll_build/$(basename "${template%.erb}")" | ||
| test -f "$page" || (echo "Missing generated page: $page" && exit 1) | ||
| done | ||
| # No .md cross-reference links should remain | ||
| if grep -rP '\]\([^):]*\.md[)#]' documentation/jekyll_build/*.md; then | ||
| echo "Found unrewritten markdown .md links" && exit 1 | ||
| fi | ||
| if grep -r 'href="[^"]*\.md' documentation/jekyll_build/*.md; then | ||
| echo "Found unrewritten HTML href .md links" && exit 1 | ||
| fi | ||
| # Nav YAML must be present and parse cleanly | ||
| ruby -e "require 'yaml'; YAML.safe_load(File.read('documentation/jekyll_build/_data/openbolt_nav.yml'))" \ | ||
| || (echo "openbolt_nav.yml is invalid YAML" && exit 1) |
Contributor
There was a problem hiding this comment.
I'd make make this a rake task and put it under rakelib/*.rake
tuxmea
reviewed
May 12, 2026
Author
There was a problem hiding this comment.
Probably not needed, but out of scope for this PR. Opened #234 to track its removal.
tuxmea
reviewed
May 12, 2026
| with: | ||
| build: dita -i documentation/bolt.ditamap -o out -f html5 --processing-mode=strict | ||
| - name: Generate and verify Jekyll docs | ||
| run: bundle exec rake docs:jekyll docs:jekyll_verify |
There was a problem hiding this comment.
How about all the includes and layout from the docs repo?
Is this taken into account?
Are includes and layout needed at all in this step?
Author
There was a problem hiding this comment.
The docs:jekyll task doesn't actually run Jekyll — it just copies the markdown files, rewrites .md links to .html, and generates the nav YAML. Includes and layouts live in the openvox-docs repo and are only needed when Jekyll builds the HTML over there. This step only validates that the content and nav data are correct before they're published. But I may have misunderstood your question :)
miharp
changed the title
Static .md files move to openvox-docs where all other OpenVox docsets live. ERB templates stay in openbolt and continue to generate reference pages from source via rake docs:all. - Remove 49 static .md files from documentation/ (move to openvox-docs) - Remove bolt.ditamap — DITA is no longer used - Rename run-dita CI job to generate-docs; remove dita-ot-action step - Add layout/title front matter to all 9 ERB templates (no permalink:) - Bake .html cross-reference links directly into ERB template content; rewrite_md_links handles remaining .md links from Ruby config option descriptions and Puppet docstrings at rake docs:jekyll time - rake docs:jekyll: renders ERB templates, rewrites source-generated .md links to .html, copies output to documentation/jekyll_build/ - rake docs:jekyll_verify: checks all 9 pages present and no .md links remain in output - Update documentation/README.md to describe ERB-only structure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
miharp
added a commit
to miharp/openvox-docs
that referenced
this pull request
May 13, 2026
Adds OpenBolt 5.x documentation as a new Jekyll collection. Static documentation pages are moved here from the openbolt repo; 9 reference pages (bolt_command_reference, plan_functions, etc.) are generated at CI time by running `rake references:openbolt`, which clones the openbolt repo and invokes `rake docs:all` to render ERB templates. - Add `openbolt_latest` / `openbolt_5x` Jekyll collections with layout and sidebar nav defaults, nav-map routing, and `docs/_openbolt_latest` symlink → `docs/_openbolt_5x` - Add 49 static documentation pages with `.html` cross-reference links - Add `PuppetReferences::Openbolt::Docs` class that runs `rake docs:all` in the vendored openbolt repo and copies the 9 generated reference pages - Wire into `puppet_references.rb`, `Rakefile`, and CI `build.yaml` - Add OpenBolt feature card to homepage Depends on OpenVoxProject/openbolt#233, which adds `rake docs:all` and updates ERB templates with Jekyll front matter. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
6 tasks
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
miharp
added a commit
to miharp/openvox-docs
that referenced
this pull request
May 13, 2026
Adds OpenBolt 5.x documentation as a new Jekyll collection. Static documentation pages are moved here from the openbolt repo; 9 reference pages (bolt_command_reference, plan_functions, etc.) are generated at CI time by running `rake references:openbolt`, which clones the openbolt repo and invokes `rake docs:all` to render ERB templates. - Add `openbolt_latest` / `openbolt_5x` Jekyll collections with layout and sidebar nav defaults, nav-map routing, and `docs/_openbolt_latest` symlink → `docs/_openbolt_5x` - Add 50 static documentation pages including collection index, release notes, and 49 pages moved from openbolt, with `.html` cross-reference links - Add `PuppetReferences::Openbolt::Docs` class that runs `rake docs:all` in the vendored openbolt repo and copies the 9 generated reference pages - Wire into `puppet_references.rb`, `Rakefile`, and CI `build.yaml` - Add OpenBolt feature card to homepage Depends on OpenVoxProject/openbolt#233, which adds `rake docs:all` and updates ERB templates with Jekyll front matter. Signed-off-by: Michael Harp <mike@mikeharp.com>
miharp
added a commit
to miharp/openvox-docs
that referenced
this pull request
May 13, 2026
Adds OpenBolt 5.x documentation as a new Jekyll collection. Static documentation pages are moved here from the openbolt repo; 9 reference pages (bolt_command_reference, plan_functions, etc.) are generated at CI time by running `rake references:openbolt`, which clones the openbolt repo and invokes `rake docs:all` to render ERB templates. - Add `openbolt_latest` / `openbolt_5x` Jekyll collections with layout and sidebar nav defaults, nav-map routing, and `docs/_openbolt_latest` symlink → `docs/_openbolt_5x` - Add 50 static documentation pages including collection index, release notes, and 49 pages moved from openbolt, with `.html` cross-reference links - Add `PuppetReferences::Openbolt::Docs` class that runs `rake docs:all` in the vendored openbolt repo and copies the 9 generated reference pages - Wire into `puppet_references.rb`, `Rakefile`, and CI `build.yaml` - Add OpenBolt feature card to homepage Depends on OpenVoxProject/openbolt#233, which adds `rake docs:all` and updates ERB templates with Jekyll front matter. Signed-off-by: Michael Harp <mike@mikeharp.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the openbolt side of OpenVoxProject/openvox-docs#98, following the approach agreed in team discussion (2026-05-13 — see #232):
.mdfiles fromdocumentation/— they move to openvox-docs where all other OpenVox docsets livedocumentation/bolt.ditamapdeleted;dita-ot-actionstep removed from CI;run-ditajob renamed togenerate-docsrake docs:allis unchangedlayout: defaultandtitle:added to all 9.md.erbfiles; nopermalink:added.htmllinks into ERB templates — cross-reference links in template-level content use.htmldirectly;rewrite_md_linkshandles the remaining.mdlinks embedded in Ruby config option descriptions and Puppet docstrings (where changing the source to.htmlwould look odd to developers)rake docs:jekyll— renders ERB templates, rewrites remaining.mdlinks from source-generated content, copies output and images todocumentation/jekyll_build/The openvox-docs copy pipeline will run
rake references:openbolt(using thePuppetReferencesframework) which callsrake docs:allin a checked-out openbolt tree and copies the 9 generated reference pages.Companion PR
OpenVoxProject/openvox-docs#191 — adds the 50 static documentation pages, Jekyll collection config, sidebar nav, and the
PuppetReferences::Openbolt::Docsclass that callsrake docs:allat CI time. That PR depends on this one merging first.Notes
documentation/jekyll_build/is gitignored — generated artifact onlypermalink:anywhere — collection-level routing in openvox-docs handles URL resolutionTest plan
bundle exec rake docs:allgenerates all 9 reference pages cleanlybundle exec rake docs:jekyllproducesdocumentation/jekyll_build/with all 9 pages and imagesbundle exec rake docs:jekyll_verifypasses (all pages present, no unrewritten.mdlinks)generate-docsjob passes