Add Preview status badge support (page-preview attribute)#398
Conversation
…iew in status-badge comment Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Deploy Preview for docs-ui ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR adds a new "Preview" status indicator feature. A helper function ( Estimated code review effort: 2 (Simple) | ~15 minutes Sequence Diagram(s)sequenceDiagram
participant Template as nav-tree.hbs / article.hbs
participant Helper as is-preview-feature.js
participant Catalog as contentCatalog
Template->>Helper: is-preview-feature(navUrl, page)
alt cache stale or missing component
Helper->>Catalog: read pages' asciidoc attributes
Catalog-->>Helper: page-preview values
Helper->>Helper: build urlCache Map keyed by pub.url
end
Helper-->>Template: boolean (preview enabled)
Template->>Template: apply cloud-preview class / render status-badge--preview
Related Issues: None mentioned Poem: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
src/helpers/is-preview-feature.js (1)
9-13: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low valueMissing guard for
page.componentbefore dereferencing.name.Line 9-10 guard against
page.layout === '404'and a missingcontentCatalog, but Line 13 dereferencespage.component.namewithout checkingpage.componentexists. If any page lacks acomponent(e.g., synthetic/generated pages), this throws.🛡️ Defensive guard
- if (!contentCatalog) return false + if (!contentCatalog || !page.component) return false🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/helpers/is-preview-feature.js` around lines 9 - 13, Add a defensive guard in isPreviewFeature before accessing page.component.name, since some pages may not have a component and would throw here. Update the cachedComponent check to safely handle missing page.component (and its name) while keeping the existing early returns for page.layout === '404' and missing contentCatalog. Use isPreviewFeature and the cachedComponent/page.component.name access as the key locations to adjust.src/css/doc.css (1)
463-486: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winHardcoded colors duplicate and diverge from the new
vars.csspreview tokens.Light mode here hardcodes
#1f2937/#f9fafbwhich happens to match the--preview-label-background/--preview-label-colordefaults in vars.css, but the dark-mode override uses a different visual scheme (rgba(148, 163, 184, 0.15)background +#cbd5e1text) than the dark override defined in vars.css (--preview-label-background:#cbd5e1solid + `--preview-label-color: `#1f2937text). This means the sticky-header pill and the inlinebadge:previewmacro (styled viametadata.cssusing the vars) will render with inconsistent color treatments in dark mode, and any future palette tweak to the vars won't propagate here.♻️ Proposed fix to consume shared tokens
.status-badge--preview { - background: `#1f2937`; - color: `#f9fafb`; - border: 1px solid `#111827`; + background: var(--preview-label-background); + color: var(--preview-label-color); + border: 1px solid var(--preview-label-border, `#111827`); }html[data-theme="dark"] .status-badge--preview { - background: rgba(148, 163, 184, 0.15); - color: `#cbd5e1`; - border-color: rgba(148, 163, 184, 0.3); + background: var(--preview-label-background); + color: var(--preview-label-color); + border-color: var(--preview-label-border, rgba(148, 163, 184, 0.3)); }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/css/doc.css` around lines 463 - 486, The preview badge styles in status-badge--preview are hardcoding colors instead of using the shared preview tokens from vars.css, which causes dark-mode inconsistency with metadata.css and the badge:preview macro. Update the status-badge--preview rules to consume the preview CSS variables (including the dark-theme values) so the sticky-header pill stays aligned with the shared token set and future palette changes propagate automatically.preview-src/preview-status-test.adoc (1)
1-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider documenting the inline
badge:preview[]macro too.The PR objective mentions
badge:preview[label=Preview]inline macro support, but this test page only covers the nav "(Preview)" indicator and sticky-header pill, not the inline badge macro. Adding a short section exercisingbadge:preview[label=Preview]would give full visual coverage for this cohort.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@preview-src/preview-status-test.adoc` around lines 1 - 17, The Preview status test page currently covers the sticky-header pill and nav indicator, but not the inline `badge:preview[]` macro. Update the `preview-status-test.adoc` content to add a short section that explicitly renders `badge:preview[label=Preview]` so the preview badge cohort is fully exercised. Keep the existing `Preview Status Test Page` structure and place the new example near the other badge demonstrations for easy discovery.src/css/vars.css (1)
130-131: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winNew preview tokens aren't consumed consistently by the sticky-header badge.
These
--preview-label-background/--preview-label-colortokens are correctly used bymetadata.css's.badge--large.badge--preview, butdoc.css's.status-badge--previewhardcodes its own hex/rgba values instead (see comment there) — including dark-mode values that don't match these overrides. Consider having doc.css consume these variables directly to avoid theme drift.Also note beta defines
--beta-label-borderbut no equivalent--preview-label-borderwas added, leaving doc.css to hardcode border colors for the preview badge.Also applies to: 201-203
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/css/vars.css` around lines 130 - 131, The preview badge styles are still hardcoding colors in doc.css instead of consuming the new preview tokens, which causes theme drift with metadata.css. Update the status-badge--preview styling to use --preview-label-background and --preview-label-color directly, and add a matching --preview-label-border token alongside the existing preview tokens so the border color can be sourced the same way instead of using hardcoded hex/rgba values. Keep the change aligned with the existing badge token usage in the preview-related CSS selectors.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@preview-src/preview-status-test.adoc`:
- Around line 1-17: The Preview status test page currently covers the
sticky-header pill and nav indicator, but not the inline `badge:preview[]`
macro. Update the `preview-status-test.adoc` content to add a short section that
explicitly renders `badge:preview[label=Preview]` so the preview badge cohort is
fully exercised. Keep the existing `Preview Status Test Page` structure and
place the new example near the other badge demonstrations for easy discovery.
In `@src/css/doc.css`:
- Around line 463-486: The preview badge styles in status-badge--preview are
hardcoding colors instead of using the shared preview tokens from vars.css,
which causes dark-mode inconsistency with metadata.css and the badge:preview
macro. Update the status-badge--preview rules to consume the preview CSS
variables (including the dark-theme values) so the sticky-header pill stays
aligned with the shared token set and future palette changes propagate
automatically.
In `@src/css/vars.css`:
- Around line 130-131: The preview badge styles are still hardcoding colors in
doc.css instead of consuming the new preview tokens, which causes theme drift
with metadata.css. Update the status-badge--preview styling to use
--preview-label-background and --preview-label-color directly, and add a
matching --preview-label-border token alongside the existing preview tokens so
the border color can be sourced the same way instead of using hardcoded hex/rgba
values. Keep the change aligned with the existing badge token usage in the
preview-related CSS selectors.
In `@src/helpers/is-preview-feature.js`:
- Around line 9-13: Add a defensive guard in isPreviewFeature before accessing
page.component.name, since some pages may not have a component and would throw
here. Update the cachedComponent check to safely handle missing page.component
(and its name) while keeping the existing early returns for page.layout ===
'404' and missing contentCatalog. Use isPreviewFeature and the
cachedComponent/page.component.name access as the key locations to adjust.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e3416368-8ccb-4625-9001-33a4dbf0c9a4
📒 Files selected for processing (8)
preview-src/preview-status-test.adocsrc/css/doc.csssrc/css/metadata.csssrc/css/nav.csssrc/css/vars.csssrc/helpers/is-preview-feature.jssrc/partials/article.hbssrc/partials/nav-tree.hbs
|
@micheleRP could we add the preview page to the nav tree so I can find it to test. |
|
Done in acde98d. The page is now in the preview nav under Troubleshooting > Preview Status Test, and here's a direct link on this PR's deploy preview: https://deploy-preview-398--docs-ui.netlify.app/preview-status-test.html You can also see the changes on a real site build: the adp-docs PR that consumes this (redpanda-data/adp-docs#126) has a deploy preview built with this branch's bundle, for example https://deploy-preview-126--redpanda-agentic-data-plane.netlify.app/agentic-data-plane/connect/managed/managed-catalog/ (catalog badges, header pills, and sidebar pills). One unrelated thing I noticed: the neighboring Limited Availability Test nav link 404s on deploy previews (it points at /streaming/24.3/..., but the page is served at the root). Left as is since it's not part of this PR. |
We may as well fix it. I don't think Troubleshooting is a good place for the preview. Most previews should go under Quickstarts because it's expanded by default. |
Quickstart is expanded by default, so the Preview Status Test and Limited Availability Test pages are easier to find there. Also corrects the Limited Availability Test URL, which pointed at /streaming/24.3/ while the page is served at the site root.
|
Done in 4c00489: moved Preview Status Test under Quickstart, and moved Limited Availability Test there too with its URL fixed (it now points at /limited-availability-test.html, where the page is actually served). Both verified clickable on the deploy preview: https://deploy-preview-398--docs-ui.netlify.app/ One scoping question: the other Quickstart nav links (Bloblang Syntax, Bloblang Playground, Property Tooltips, Home page, and the Hardware & Software Requirements entry) 404 the same way, because they also point at /streaming/24.3/ while the pages are served at the root. Want me to fix those in this PR as well, or leave them for a separate cleanup? |
|
Looks good. Makes sense to fix any issues here. also when this is merged, you’ll need to push a new version tag to kick off the build and publish the release. |
redpanda-data/docs-ui#398 merged and v3.1.6 shipped with page-preview theme support (verified: catalog badges, header pills, sidebar pills, and dark-mode CSS vars all render against the real released bundle). Points local-antora-playbook.yml back at releases/latest and drops the temporary local bundle used for PR 126's deploy preview. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2 participants
What
Adds first-class
Previewmaturity-badge support to the theme, cloned from the existing beta machinery (which is untouched)::page-preview: truerenders a(Preview)pill on sidebar nav links (is-preview-featurehelper +cloud-previewclass), and aPreviewstatus pill in the sticky page header with a tippy tooltip. Tooltip text defaults to "This feature is in preview and may change." and can be overridden with:page-preview-text:.badge:preview[label=Preview](thebadgeinline macro) gets.badge--preview/.badge--large.badge--previewstyling via new--preview-label-*theme variables, with dark-mode overrides matching the sibling badges.preview-src/preview-status-test.adocfor the local UI preview.Why
The Agentic Data Plane UI (ai.redpanda.com) now labels pre-GA features with a single Preview tag. The ADP docs are moving from beta to Preview to match; an upcoming adp-docs PR consumes this. Other components' beta badges are unaffected.
Verification
npx gulp preview:build: compiled test page HTML contains the badge span and default tooltip; compiled site.css contains the new classes and both light/dark variable definitions.Note for release
The adp-docs change depends on this reaching the
releases/latestui-bundle, so av*tag after merge would be appreciated.🤖 Generated with Claude Code