Skip to content

Source the Connect reference partials from the Connect release asset - #5

Merged
JakeSCahill merged 6 commits into
mainfrom
docs/source-connect-partials
Oct 10, 2026
Merged

JakeSCahill merged 6 commits into
mainfrom
docs/source-connect-partials

Conversation

@JakeSCahill

@JakeSCahill JakeSCahill commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Registers the modify-connect-tag-playbook extension so the Connect reference partials (fields, examples, metadata, descriptions, and the Bloblang reference) come from the latest Connect release instead of rp-connect-docs.

Connect no longer commits its generated docs. Each Connect release attaches them as redpanda-connect-docs.tar.gz, and the extension downloads that asset and adds the files to the connect component. This playbook doesn't list the connect repo as a content source.

Notes:

  • Bumped to docs-extensions-and-macros 5.54.0, which includes feat(rpcn-docs): source connect reference docs from the release asset docs-extensions-and-macros#358 (the asset mode), so the extension takes effect as soon as this merges.
  • Drops modify-redirects, which docs-extensions-and-macros no longer ships, so requiring it fails the build.
  • Registers set-available-attachment-versions, as docs-site does, so the Bloblang playground's connect-json-url points at the newest connect-<version>.json that exists instead of one auto-docs hasn't generated yet.
  • Merge this before redpanda-data/rp-connect-docs#531, which removes the partials rp-connect-docs still commits.

@JakeSCahill
JakeSCahill marked this pull request as ready for review September 27, 2026 18:06
@JakeSCahill
JakeSCahill requested a review from a team as a code owner September 27, 2026 18:06
5.52.0 has the modify-connect-tag-playbook version that keeps only the
generated partials and examples from the connect source.
docs-extensions-and-macros removed it in 5.30.0. Antora's own redirect
producer runs on every build without an extension.
…ease asset

Connect no longer commits its generated docs, so its next release has no
docs/antora.yml and Antora would fail to aggregate the source. The
modify-connect-tag-playbook extension adds the partials from the release
asset instead, once docs-extensions-and-macros ships that mode.
@JakeSCahill JakeSCahill changed the title Add the connect repo as a content source for Connect reference partials Source the Connect reference partials from the Connect release asset Oct 7, 2026
@Feediver1

Copy link
Copy Markdown

Heads-up: please hold this PR until redpanda-data/docs-extensions-and-macros#358 is released.

redpanda-data/connect#4863 merged today, so upcoming Connect releases will no longer include docs/antora.yml. They attach the generated docs as a redpanda-connect-docs.tar.gz release asset instead. On d-e-m 5.52.0, this PR's url: https://github.com/redpanda-data/connect / tags: latest source gets pinned to the newest release. Once that release lacks docs/antora.yml, Antora stops with "antora.yml not found". After #358 ships, the extension reads the release asset and the content source is no longer needed.

So once #358 is released, this PR can drop the connect content-source lines, keep only the modify-connect-tag-playbook registration, and bump to that release.

@JakeSCahill
JakeSCahill marked this pull request as draft October 8, 2026 18:03
@JakeSCahill
JakeSCahill marked this pull request as ready for review October 9, 2026 15:36
@Feediver1

Copy link
Copy Markdown

Technical check: Connect release-asset cutover

Overall: Ready to merge. This repo has no CI checks or deploy preview, so I built it locally at 31e2788. The build exits 0 with the Connect pages intact, which matters because this PR jumps docs-extensions-and-macros two major versions (3.7.0 to 5.54.0).

Hold conditions: all met

These are the same as on the sibling PRs (redpanda-data/docs#2117, redpanda-data/cloud-docs#748, redpanda-data/adp-docs#356, redpanda-data/redpanda-labs#309): redpanda-data/connect#4876 merged, Connect v4.113.0 ships the asset, redpanda-data/docs-extensions-and-macros#358 is in v5.54.0, the content-source lines were dropped (0f029c72), and the bump is in 31e2788.

Local build at 31e2788

Check Result
npm ci 2,369 packages, exit 0
antora --fetch Exit 0, 9,150 HTML pages
Log 1 error, 43 warnings. None of them comes from this PR (details below).
Connect output connect/components/outputs/kafka_franz/ renders with 108 unique IDs

Where the log messages come from:

  • The one error: xref:home:ROOT:how-to-use-these-docs.adoc in cloud-docs' cloud-mcp/overview.adoc. The home component lives in docs-site, which this playbook doesn't aggregate.
  • 39 warnings: tag 'deprecated' or 'exclude-from-docs' not found in include file, from aggregated content.
  • The rest: two Cloud docs missing for: websocket notices from the 4.113.0 connector data, one missing-attribute warning, and a stale site.start_page (suggestion 2).

Suggestions

  1. The PR body is out of date. The same bullet as on the siblings asks for the bump, and the body should also say why modify-redirects was removed. Consider: "Bumped to 5.54.0 (includes #358), up from a lockfile pinned at 3.7.0. Drops modify-redirects, which docs-extensions-and-macros no longer ships."

  2. Not caused by this PR: the template's start page is stale. The build warns Start page specified for site not found: ROOT:get-started:intro-to-events.adoc. New repos copy this playbook, so it's worth fixing in a follow-up.

  3. Not caused by this PR: the same Bloblang JSON 404 as the siblings. The local build sets connect-json-url to https://docs.redpanda.com/connect/components/_attachments/connect-4.113.0.json, but only connect-4.112.0.json is published. Registering set-available-attachment-versions fixes it.

Impact on other repos

  • redpanda-data/rp-connect-docs#531: the same note as on the sibling PRs. The release asset doesn't include connect-<version>.json, so that file still depends on rp-connect-docs' auto-docs regen after the cutover.

What works well

  • The two-major-version jump is safe. All 17 extension and macro paths in the playbook exist in 5.54.0, and Antora (3.1.2) and Asciidoctor (2.2.6) are unchanged. The only other version changes are two Octokit patch bumps.
  • Pinning ^5.54.0 instead of "latest" makes package.json match what the lockfile actually installs.
  • Correct extension order: modify-connect-tag-playbook is now first, before generate-rp-connect-info.

@JakeSCahill

Copy link
Copy Markdown
Contributor Author

Thanks @Feediver1. Updated the description, and f966876 registers set-available-attachment-versions after the version fetcher, as docs-site does, so connect-json-url points at the newest connect-<version>.json that exists. I'll fix the stale start page in a separate PR.

@micheleRP micheleRP left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

LGTM. Lockfile resolves docs-extensions-and-macros 5.54.0, and the playbook only affects PR previews.

@JakeSCahill
JakeSCahill merged commit 21e0e27 into main Oct 10, 2026
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.

3 participants