The Great Docs Reset of 2026#45
Merged
Merged
Conversation
This commit updates the Gemfile to bring in the Jekyll-VitePress theme: https://jekyll-vitepress.dev/ The beginnings of a new documentation site, with a modern Jekyll layout, are started with `_config.yml` and `index.md` in the root directory. The remnants of the old docs site are ignored, for now. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit moves the `source/facter/5.5` directory over to `docs/_openfact_5x` and adds an `_openfact_latest` symlink pointing at it. The Jekyll site configuration is updated to look under the `docs/` directory for documentation "collections", with these 5.x docs output into the final site build as both `openfact/latest` and `openfact/5.x`. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit adds a set of GitHub actions that build and deploy the documentation website. The `build.yaml` action checks out the docs repository, runs `jekyll build` and then creates a versioned tarball artifact from the resulting output. This ORAS CLI is used to publish this artifact to the GitHub Container Registry. Publishing to the Container Registry creates a durable history of published content that can be retrieved and used independently of GitHub. The `deploy.yaml` workflow pulls an artifact from the Registry and uses the official `actions/upload-pages-artifact` and `actions/deploy-pages` Actions to deploy the content to GitHub pages. Finally, an `autopublish.yaml` workflow is added that triggers both the build and deploy workflows in reaction to pushed changes to documentation files. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit adds a script `util/html-toc-to-nav.rb`, that reads the old Puppet Docs HTML table of contents format used by files like `source/facter/_facter_toc.html` and `source/puppet/latest/_puppet_toc.html` and renders the navigation structure to a YAML document. The format of this document follows the configuration used by the VitePress static site generator. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit overrides the `_includes/sidebar.html` inherited from the VitePress theme with a version that allows for per-collection sidebars defined by YAML files under `_data/nav/`. Multiple nesting levels are also supported, although the expand/collapse functionality is not implemented beyond the first level. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit adds a `_data/nav/openfact_5x.yaml` data map that defines the sidebar content for openfact. This data was generated by from `source/facter/_facter_toc.html` using `util/html-toc-to-nav.rb` with some manual fixups of the resulting output. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit disables the "previous page" and "next page" links that the Jekyll-VitePress theme generates for the bottom of each doc page. The logic for generating these does not account for the custom per-collection navigation defined in `_data/nav/*.yaml`, so they end up being a source of confusion. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit adds various OpenVox logos from the `voxpupuli/logos` repository to the documentation. Ideally, these assets should be compiled into the static builds, but they are inserted as external references for now. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit pulls the Puppet 5.5 documentation tree back from the depths of git history. Specifically: commit a9dfea5. This was the last commit before the Puppet Docs team started migrating Markdown files to the closed DITA documentation system. Thus, the content in this commit is a useful starting point for re-building a complete set of documentation for the OpenVox Agent. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit imports the Puppet 5.5 docs as the "OpenVox 8.x" documentation set. The Puppet 5.5 docset is used as a starting point because it is the last complete source entirely in markdown. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit removes a couple of include statements that point to files that exist outside of the Puppet 5.5 docset. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
The `partial` statement is a custom extension that the old `puppet-docs` project used. This patch replaces it with Jekyll's native `include_relative`. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This was referenced Apr 15, 2026
Several Puppet projects used a markdown table of contents fragment to define the left-hand nav structure. This commit adds a simple ruby script that parses those fragments and outputs a YAML tree structure. This sort of nav data structure is generally used by other doc generators, such as VitePress and Docusaurus. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit adds sidebar and other navigation data to link in the OpenVox docs. The `_data/nav/openvox_8x.yml` was generated from `docs/_openvox_8x/_puppet_toc.html` using `util/mdtoc-to-nav.rb` and then hand-edited to remove links to the Facter and PuppetServer docsets as a simplification. These can be re-added later. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
This commit sets `release_nodes.markdown` as the index file for the OpenVox docs, for no reason other than it is listed first in the table of contents. Signed-off-by: Charlie Sharpsteen <charlie@overlookinfratech.com>
Sharpie
force-pushed
the
the-great-docs-reset
branch
from
f49a588 to
7dafb11
Compare
jay7x
approved these changes
Apr 15, 2026
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
2 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.
Short description
The
puppet-docsproject thatopenvox-docswas forked from has been in a somewhat overgrown and incomplete state ever since 2018 when the Puppet Docs team started migrating away from Markdown content towards internal publishing systems that were not accessible to the community. This changeset represents an attempt to reset the documentation repository to a state that will support iteration and cleanup by community members.The list of files modified by this change set is, apologetically, massive, so here is the summary:
_config.yml,_includes/and_data/. Top-level landing page is defined inindex.md. Documentation for individual projects is located under thedocs/directory. Site can be built by runningbundle exec jekyll buildin the root directory.source/facter/directory.source/puppet/5.5directory at commit a9dfea5.masterbranch. Generated website is set up to be served from the root directory of a sub-domain, i.e.docs.openvoxproject.orgthat is a DNSCNAMEpointing toopenvoxproject.github.io.The VitePress Jekyll theme could be swapped out easily if needed, no deep dependences have been created on it. This change set does not clean up or modify the old
puppet-docscode, that site can still be built viaraketasks if needed.This changeset includes some content generated by Anthropic's Claude LLM. This LLM usage is limited to re-writes of the table of contents displayed in the sidebar of the OpenFact and OpenVox documentation sets.
An example of the fully deployed site, after these changes, can be found here:
https://openvox-docs.stumpworx.net
Checklist
I have:
Signed-off-byannotation to each of my commits