docs(ep-v2): document hidden: true page frontmatter - #4447
Conversation
Enterprise Portal v2 can keep a page unpublished with hidden: true in markdown frontmatter. Document the flag next to visible_when, including TOC subtree behavior, home overrides, and preview.
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
…shooting - Distinguish hidden (unpublished) from visible_when (per-customer gating) - Add scenario-led "why" for hidden: true (staging drafts in the git flow) - Troubleshooting: note that unparseable frontmatter is treated as unpublished Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
| - Verify visibility rules (entitlements, channels) | ||
| - Check frontmatter `visible_when` conditions | ||
| - Confirm the page frontmatter does not set `hidden: true`. Hidden pages stay unpublished for every customer, including in local preview | ||
| - Confirm the page frontmatter parses as valid YAML. Frontmatter that Enterprise Portal cannot parse is treated as unpublished, so the page is hidden from every customer, including in local preview |
There was a problem hiding this comment.
This is a bit broader than the implementation. Invalid YAML fail-closes as unpublished (frontmatter.go:L58-L59), but valid YAML with a type error (like tags: draft) does not hide the page unless hidden: true is set (frontmatter_test.go:L23). Can we say "invalid YAML is treated as unpublished" instead of "frontmatter that Enterprise Portal cannot parse"?
There was a problem hiding this comment.
Good catch, corrected in 9d8daeb. Reworded to "Invalid YAML is treated as unpublished" so it no longer implies a typed-parse failure like tags: draft hides the page.
|
|
||
| `hidden` controls whether a page is published, not who can see it. Use `visible_when` to show a page to some customers and not others based on their license. Use `hidden: true` to keep a page out of every customer's portal until you are ready to publish it, regardless of license. | ||
|
|
||
| Set `hidden: true` in a page's YAML frontmatter when the page belongs in your content repo but is not ready for customers yet. For example, stage a product announcement, a new install guide, or a revised section next to your live docs, keep its entry in `toc.yaml` so local preview shows where it sits in the navigation, then publish it by removing the flag when you are ready. Draft pages stay under version control in the same repo and pull request flow as your published content, so nothing lives in a stray branch or an unwired file you have to remember later. |
There was a problem hiding this comment.
This says local preview will show the unpublished page in the nav, but enterprise-portal-v2-content.mdx:L762 says the opposite. Preview prunes hidden: true the same way prod does (run.go:L195-L199), so it won't show in the preview sidebar either.
Can we keep "leave it in toc.yaml" but change the reason? The TOC entry is so the nav slot is already wired when you unhide it, not so preview can display it. If we say that here, we can drop the duplicate sentence in the note.
There was a problem hiding this comment.
Fixed in 9d8daeb. Changed the reason to nav-slot pre-wiring, added a line that preview hides the page like production, and dropped the now-duplicate preview sentence from the note.
- Troubleshooting: only invalid YAML fails closed (not any typed-parse failure) - Why: toc.yaml entry pre-wires the nav slot; preview hides the page like prod - Drop the now-redundant preview line from the note Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3 participants
Summary
Document Enterprise Portal v2 page frontmatter
hidden: trueso vendors can keep a page in the content repo andtoc.yamlwithout publishing it.Implements docs for sc-138380. Implementation: vandoor#10449.
Why
Vendors could omit a page from
toc.yamlor gate it withvisible_when, but there was no documented way to leave the nav slot in place and keep the page unpublished.hidden: trueis unpublished content, not a license or entitlement gate. It takes precedence overvisible_when.Changes
enterprise-portal-v2-content.mdxtoc.yaml(allowlist) fromhidden: true(keep the TOC entry, unpublished)overrides.homecannot restore a hidden page, andhidden: truecan hide the home landing pagepageis hidden is dropped with its subtree; title-only sections cannot usehiddenhidden: truenext to frontmattervisible_when, with a page example and a matchingtoc.yamlentryenterprise-portal-v2-troubleshooting.mdx— pages missing from navigation can be unpublished withhidden: trueenterprise-portal-v2-use.mdx— customer-facing nav also respects unpublished pagesNo changes to
enterprise-portal-v2-versioned-docs.mdx. Hidingmainas a draft branch is a different feature.Validation
git diff --check