Skip to content

docs: Add guide for generating versioned docsets.#442

Open
kapunahelewong wants to merge 1 commit into
bazel-contrib:mainfrom
kapunahelewong:add-versioned-docs-guide
Open

docs: Add guide for generating versioned docsets.#442
kapunahelewong wants to merge 1 commit into
bazel-contrib:mainfrom
kapunahelewong:add-versioned-docs-guide

Conversation

@kapunahelewong
Copy link
Copy Markdown
Collaborator

@kapunahelewong kapunahelewong commented May 9, 2026

Adds an end-to-end guide for generating and publishing a versioned documentation
snapshot for a new Bazel release.

What's in the guide

  • Two build paths: detects whether the release branch has MDX tooling
    (Path A: gen_mdx_release_docs) or needs the older pipeline plus
    docs2mdx.py (Path B), with a one-liner to check before starting
  • Prerequisites: Bazelisk, GNU grep (macOS), Mintlify CLI, GitHub CLI,
    Python deps for Path B
  • 9 steps end-to-end with copy-pasteable commands split by path where
    they differ
  • MDX fix checklist: 6 error categories (Jekyll anchors, {: .external},
    Jinja-escaped tags, DevSite metadata, non-self-closing void elements) with
    exact sed/perl one-liners
  • AI prompt for harder-to-automate fixes (unescaped </> in prose,
    <pre> blocks with special characters)
  • Anchor restoration: shell snippet to find the best source version
    dynamically rather than hardcoding a version number
  • Gotchas inline: UNSAFE_ version stamps, wrong base branch, double-nested
    extraction, CLA bot, command-line-reference.mdx presubmit failure
  • Final checklist to run through before submitting the PR

@kapunahelewong kapunahelewong marked this pull request as draft May 9, 2026 00:11
@kapunahelewong
Copy link
Copy Markdown
Collaborator Author

Keeping this in draft mode until I can test it to confirm accuracy.

@kapunahelewong kapunahelewong force-pushed the add-versioned-docs-guide branch from 86b998c to bd7ffae Compare May 13, 2026 22:20
@kapunahelewong kapunahelewong force-pushed the add-versioned-docs-guide branch from 06a07c5 to 9b76155 Compare May 13, 2026 23:03
@kapunahelewong kapunahelewong marked this pull request as ready for review May 13, 2026 23:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant