1.0 docs flip - #495
Merged
Merged
1.0 docs flip#495
Conversation
Phase 1 of RELEASE-1.0-CHECKLIST.md — the flip. Mechanical: no content changes, only the plumbing that was holding 1.x back. Drop the draft cascade and retitle 1.x out of preview, restore the 1.x entry in hugo.yaml first in the list and labeled current, move `latest` from 0.x to 1.x, give 0.x a superseded-version banner, and delete the hugo.preview.yaml overlay along with its wiring in the Makefile, preview.yaml and links.yml. A plain `hugo --config hugo.yaml` now renders 108 1.x pages where it rendered zero. Order in the versions list is load-bearing beyond the dropdown: resolve-latest-version.html keys off a `linkVersion` of literally "latest" and, finding none, falls back to the first entry, which is what the PDF cover and running footer print. Also adds a local override of utils/version-noindex.html. The upstream partial builds a page's current-version equivalent from version-root's lookupPath and passes it to site.GetPage, but this site's baseURL is https://kagent.dev/docs/, so that path carries a /docs/ segment coming from the baseURL rather than from a content directory. GetPage resolves content-relative paths, so every lookup missed and the partial emitted nothing on any page. That was invisible while `latest` sat on 0.x and 1.x was withheld; moving the flag would otherwise have had no effect. The override strips the site's home prefix before the lookup and changes nothing else. Still unfixed upstream as of v0.3.12. Verified against a production build: the dropdown reads 1.x (current) then 0.x, all 107 0.x pages carry the banner and none of the 1.x pages do, the 15 0.x pages that exist in both trees get noindex and no 1.x page does, and the {{< version include-if="1.x" >}} conrefs render non-empty without the overlay. Link check against the pre-flip build reports zero new failures. Signed-off-by: Rachael Graham <rachael.graham@solo.io> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
The generated kagent CLI pages built their Subcommands and _index.md cross-links from --url-prefix, producing hardcoded root-relative paths like /docs/kagent/1.x/reference/cli/kagent-apply/. That is correct on this site and wrong anywhere the page is reused: the enterprise docs hub rebases these pages under its own version, and rebase rewrites the /docs prefix but cannot remap a version segment it has no way to recognize, so all 39 links kept pointing at the OSS 1.x tree. generate-cli-docs.py now takes an optional --link-prefix. When set, those links are emitted as the theme's version- and product-aware `link` shortcode instead, so one source resolves correctly in both places. The update-ref-docs workflow passes it for kagent only; kmcp has no version tree for the shortcode to resolve against and keeps the URL form. The 0.x regeneration recipe in the workflow header keeps the URL form too, noted inline: 0.x is frozen and is not rebased downstream. The 39 links in the committed 1.x pages are rewritten to match what the generator now produces, so the next scheduled run is a no-op rather than a large diff. Verified: the OSS build resolves the same 39 URLs it did before, and a downstream build of the enterprise hub against this branch resolves them to that hub's own version with no OSS version segment left anywhere. Signed-off-by: Rachael Graham <rachael.graham@solo.io> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The root-relative /docs/kmcp/ is correct on this site and breaks downstream. The enterprise docs hub rebases this page and rewrites the /docs prefix, turning the link into /kagent/kmcp/ — a path that does not exist there, because kmcp is not part of that product. kmcp docs are published only here, so an absolute URL is the destination either way and is left alone by that rewrite. Signed-off-by: Rachael Graham <rachael.graham@solo.io> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
commented
Sep 16, 2026
| | `provider.organization` | Name of the organization responsible for the agent. | | ||
| | `provider.url` | URL to the agent provider's website or documentation. Must be a valid URI. | | ||
|
|
||
| ## A2A AgentCard metadata |
Contributor
Author
There was a problem hiding this comment.
duplicate section
Rachael-Graham
commented
Sep 16, 2026
|
|
||
| Both fields are optional. When neither is set, botocore defaults apply and existing behavior is unchanged. | ||
|
|
||
| ## Bedrock Guardrails |
Contributor
Author
There was a problem hiding this comment.
duplicate section
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
marked this pull request as ready for review
September 18, 2026 16:18
kristin-kronstain-brown
approved these changes
Sep 18, 2026
Nadine2016
approved these changes
Sep 18, 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
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.
What this does
Publishes the
content/kagent/1.x/doc set that #493 added behind a draft cascade, and labels it as the kagent 1.0 beta rather than as the current release.1.0 ships as a beta, so 0.x stays the current supported version.
latestdoes not move off the 0.x entry, both versions carry a banner saying which release a reader is looking at, and the marketing links and the legacy/docs/kagent/*redirect keep pointing at 0.x until GA.Publishing the 1.x tree
Three things kept 1.x out of a production build, and each had a matching piece of temporary plumbing to remove:
draft: trueand thecascade.draftkey, retitle out of previewdocs-site/content/kagent/1.x/_index.mddocs-site/hugo.preview.yaml-DMakefile,.github/workflows/preview.yaml,.github/workflows/links.ymlA plain
hugo --config hugo.yamlnow renders every 1.x page, list page, andllms.txtentry, so the link checker keeps the 1.x coverage it gained while the overlay existed.make serve-docsalso drops-D, which means local authoring now matches production.Version labeling
The
versionslist indocs-site/hugo.yamlis where 1.x is declared a beta rather than the current release:1.x sits first so the switcher reads newest-first. Order carries no other meaning on this site:
resolve-latest-version.htmlfalls back to the first entry, but its only callers are the PDF book cover and the print-book running footer, and this site enables nobookoutput format.Search indexing
latest: trueis the single signal the theme'sversion-noindex.htmlaccepts, and it stays on 0.x. That partial addsnoindex, followto a non-latest page whenever the same path exists in the latest version, so the 15 1.x pages that also exist under 0.x are withheld from search and the rest of the 1.x tree is indexed normally. No 0.x page is affected. Moving the flag to the 1.x entry at GA reverses the polarity in one line.This PR also adds
docs-site/layouts/partials/utils/version-noindex.html, an override the flag needs in order to do anything at all. kagent'sbaseURLends in/docs/, so everyRelPermalinkcarries a/docs/segment that comes from the baseURL path rather than from a content directory. Upstream feeds that path straight tosite.GetPage, which resolves relative tocontentDirand therefore never matched: no duplicate was ever found and the partial emitted nothing on any page. The override strips the site's own home prefix before the lookup and changes nothing else. It was invisible until now, because a single rendered version gives the partial nothing to mark either way.Theme bump
docs-theme-extrasv0.3.8 → v0.3.12, which addsutils/md-strip-glossary.html. That partial keeps glossary tooltip definitions out of the.mdoutputs and the Copy-as-Markdown payload by matching the tooltip markup as a literal adjacency, so the localgloss.htmloverride is re-synced against v0.3.12 to preserve it. The override's own delta is unchanged: it opens a new tab only for an absolutehttp(s)destination, so an internal cross-reference stays in the current tab.Verified
Built with
hugo --config hugo.yaml --gc --minifyand checked against the output rather than the config:noindex, follow, all of them paths that also exist under 0.x, including the 1.x landing page. Zero 0.x pages carry it.linkCheckerpasses on this branch.Still blocked on the release itself
docs-site/assets/kagent-docs/versions/kagent.mdpins the 1.x span at1.0.0-beta0, and no 1.x tag exists onkagent-dev/kagentyet. Until it matches the published tag, thehelmcommand onsetup/installation.mdfails for anyone who runs it.