Skip to content

Replace dead pup.pt short links with docs.openvoxproject.org URLs - #279

Merged
corporate-gadfly merged 1 commit into
OpenVoxProject:mainfrom
miharp:fix-277-replace-pup-pt-links
Jul 22, 2026
Merged

Replace dead pup.pt short links with docs.openvoxproject.org URLs#279
corporate-gadfly merged 1 commit into
OpenVoxProject:mainfrom
miharp:fix-277-replace-pup-pt-links

Conversation

@miharp

@miharp miharp commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Fixes #277

The pup.pt redirector no longer resolves slugs. Every one of them bounces to a parked lander page:

$ curl -sL https://pup.pt/bolt-commands
<!DOCTYPE html><html><head><script>window.onload=function(){window.location.href="/lander"}</script></head></html>

The hostname is also on the resale market, so whoever buys it inherits URLs that OpenBolt prints in CLI help text, JSON schemas, generated Puppetfile comments, and error messages.

This replaces all 59 actionable references with full https://docs.openvoxproject.org/openbolt/latest/ URLs — the convention README.md and CONTRIBUTING.md already use. The 12 hits in CHANGELOG.md and HISTORY.md are left alone as historical release records.

Location Count
lib/bolt/bolt_option_parser.rb 24
guides/*.yaml 18
lib/bolt/** (other) 15
schemas/*.json 2

Rather than a replacement short domain: the indirection is what failed here. A third-party redirector disappeared and took 59 links with it, silently, with no way for CI to notice. A new domain would add a renewal obligation and a redirect map to maintain, for the sake of URL length in help text.

Notes for review

  • Schema JSON is generated, not hand-edited. The two hits come from the OPTIONS hashes in lib/bolt/config/options.rb and lib/bolt/inventory/options.rb; rake schemas:all reproduces the committed output exactly.
  • guides/links.yaml is what bolt guide links prints. Beyond its pup.pt entries it still advertised bolt.guide, slack.puppet.com, and puppetlabs/bolt, so those are updated to their OpenVox equivalents in the same pass. The replacement URLs are too long for its two-column layout, so each URL now sits on its own line to keep the output inside 80 columns. Same reason for a one-line reflow in guides/transports.yaml.
  • bolt-reference splits by context. In transports.yaml it documents transport options, so it points at bolt_transports_reference.html. In links.yaml it was a generic "Reference Documentation" entry; pointing it at the docs root would duplicate the entry above it, so it became "Configuration Reference" → configuring_bolt.html.
  • lib/bolt/analytics.rb had no valid target. It pointed at an analytics opt-out page that does not exist in the OpenBolt docs. Analytics are force-disabled in this fork (config = { 'disabled' => true }) and the message sat inside unless ENV['BOLT_DISABLE_ANALYTICS'] || true, so it was unreachable. The block is removed rather than repointed. Flagging in case anyone wants it kept.
  • openvox-docs carries the same comment in its sample Puppetfile, but that comes from lib/bolt/module_installer/puppetfile.rb, so a docs regen picks this up. No companion PR needed.

Verification

  • Every target URL returns 200, checked live. The anchors — including the three call sites that carry their own (#modulepath, #specify-a-transport, #transport-configuration) — were checked against the rendered heading IDs.
  • rake schemas:all produces no diff beyond the committed change.
  • rubocop clean.
  • rspec spec/unit: 1804 examples, 5 failures. All 5 are in plugin_spec.rb / puppet_library_spec.rb and fail identically on unmodified main, so they are pre-existing and unrelated.
  • bolt guide links and bolt guide transports render correctly.

Follow-up worth its own issue

Nothing prevents this from recurring the same silent way. A periodic link check over lib/, guides/, and schemas/ in CI would have caught it.

Reported by Yury Bushmelev.

AI usage disclosure

Per the Vox Pupuli and OpenVox AI Usage Policy: I used Claude Code for this patch — the substitution across all 59 call sites, the live verification of each target URL and anchor, the rubocop/rspec/schema-regen checks reported above, and a first draft of this description. The commit carries a Co-Authored-By trailer.

The two spots that most warrant a human eye are called out under "Notes for review": the bolt-reference context split, and the analytics block removal, which is the only behavior change here.

@miharp
Replace dead pup.pt short links with docs.openvoxproject.org URLs
3937b4b 
The pup.pt redirector no longer resolves slugs; every one of them now
bounces to a parked lander page, and the hostname is on the resale
market. Point the links at full URLs under the domain we control
instead of standing up a replacement short domain. This matches the
convention README.md and CONTRIBUTING.md already use.

Covers all 59 actionable references, in lib/, guides/, and schemas/.
CHANGELOG.md and HISTORY.md are left alone, since they are historical
release records. The schema JSON is regenerated from the OPTIONS
hashes rather than edited by hand.

Also in guides/links.yaml, which is what `bolt guide links` prints:
replace bolt.guide, slack.puppet.com, and the puppetlabs/bolt repo with
their OpenVox equivalents, and put each URL on its own line so the
output still fits an 80-column terminal.

One reference had no mapping. lib/bolt/analytics.rb pointed at an
analytics opt-out page that does not exist in the OpenBolt docs.
Analytics are force-disabled in this fork and the message was
unreachable, so the block is removed.

The sample Puppetfile in openvox-docs carries the same comment, but it
comes from lib/bolt/module_installer/puppetfile.rb, so a docs regen
picks this up.

Reported by Yury Bushmelev.

Fixes OpenVoxProject#277

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Signed-off-by: Michael Harp <mike@mikeharp.com>
corporate-gadfly
corporate-gadfly approved these changes Jul 22, 2026
View reviewed changes

@corporate-gadfly corporate-gadfly left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@corporate-gadfly
corporate-gadfly merged commit 9f37fe7 into OpenVoxProject:main Jul 22, 2026
50 checks passed
@miharp

miharp commented Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

@tuxmea You're right, and I've fixed it in 340ccdd — thanks for catching it.

One correction on the form, though: per openvox-docs CONTRIBUTING § Linking, links within a versioned collection should be bare page.html, not /openbolt/latest/page.html. Rooted /latest/ paths are the thing that guidance explicitly warns against, since they silently cross version boundaries when a new major collection is added. So plans.html, not /openbolt/latest/plans.html.

The dividing line I've landed on is whether a given string is ever rendered as a docs page.

Relative — rendered into the collection

The option descriptions in lib/bolt/config/options.rb and lib/bolt/inventory/options.rb. These feed bolt_project_reference / bolt_defaults_reference / bolt_transports_reference and the JSON schemas. Their siblings were already relative — projects.md, module_structure.md, supported_plugins.md#task, troubleshooting.md#... — so my absolute URLs were the only ones out of step.

I used the .md form rather than .html because the importer at lib/puppet_references/openbolt/docs.rb rewrites relative .md → .html on the way in:

# Rewrite relative .md cross-reference links to .html so Jekyll serves
.gsub(/(\]\([^):]*?)\.md((?:#[^)]*)?)\)/, '\1.html\2)')

Note that regex excludes anything containing :, which is why absolute URLs passed through untouched and the problem was invisible.

The awkward case — bolt_option_parser.rb

These 24 strings are dual-purpose. They're printed by bolt --help, where a relative link has no base to resolve against, and they're also imported as bolt_command_reference.md (it's in the importer's GENERATED_PAGES). 16 of them land on that page.

Breaking one context to satisfy the other seemed wrong, so rakelib/docs.rake now rewrites the absolute URLs into relative markdown links as it generates that page:

docs_url = %r{https://docs\.openvoxproject\.org/openbolt/latest/(\S+?\.html(?:\#[\w-]+)?)}
relative_docs_links = lambda do |text|
  text.gsub(docs_url) { "[#{Regexp.last_match(1)}](#{Regexp.last_match(1)})" }
end

Terminal output keeps full URIs; the generated page now has zero absolute links. Verified by regenerating with rake docs:all and grepping both.

Absolute, deliberately

Guide output (bolt guide inventory), error messages, and the comments written into generated Puppetfiles and plan templates. None of these is ever rendered as a docs page — a user looking at plans.html in their terminal, or in a comment at the top of their own Puppetfile, has nothing to resolve it against.

The offline-container point is exactly what pushed me toward fixing this in the generator rather than doing a blanket find-and-replace.

Two things I noticed while tracing this, both pre-existing and out of scope here, but worth someone's attention:

  1. bolt_inventory_reference.md is not in the importer's GENERATED_PAGES list, yet openbolt still generates it and openvox-docs carries a checked-in copy. That page looks like it may be drifting from its source.
  2. The .md vs .html convention is inconsistent across these files — options.rb uses .md while documentation/templates/bolt_types_reference.md.erb uses .html (e.g. plan_functions.html#run_plan). Both work, since the importer only rewrites the .md form, but it's a trap for the next person. I matched the local convention in each file rather than change it here.

@miharp miharp mentioned this pull request Jul 22, 2026
Open
@miharp

miharp commented Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Heads-up: this merged at its first commit (3937b4b9), so the relative-link fix from the comment above (340ccdd8) did not make it onto main. The merge landed while that commit was being pushed.

Reopened as #280, rebased onto current main. @tuxmea's point is addressed there, not here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@corporate-gadfly corporate-gadfly corporate-gadfly approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Replace dead pup.pt short links with docs.openvoxproject.org URLs

2 participants

@miharp @corporate-gadfly