Publication and Visibility Architecture
The Lowgile documentation site uses frontmatter metadata and centralized visibility helpers to control whether documentation is exposed to readers. This architecture separates editorial state, release visibility, and navigation presentation so that each concern can change independently.
The authoritative reader-visibility rule is:
visible =status === "published"ANDrelease === trueA document is reader-visible only when it is both editorially published and released.
1. Publication metadata
Section titled “1. Publication metadata”status
Section titled “status”status represents the editorial state of a documentation page. Supported values are:
status: draftstatus: reviewstatus: publishedThe content schema defines the field as:
status: z.enum(["draft", "review", "published"]).default("published")The default remains published for backward compatibility with existing documentation that does not yet declare a status.
release
Section titled “release”release determines whether the documentation may be exposed to readers. Supported values are:
release: truerelease: falseThe content schema defines the field as:
release: z.boolean().default(true)The default is true so existing documentation remains visible without requiring an immediate migration of every MDX file. Use release: false primarily for completed documentation about functionality that has not yet been released.
For example:
status: publishedrelease: falseThis combination means that the documentation is complete but must remain hidden until the related product feature is released.
Reader-visibility matrix
Section titled “Reader-visibility matrix”| Status | Release | Reader-visible |
|---|---|---|
draft | true | No |
draft | false | No |
review | true | No |
review | false | No |
published | false | No |
published | true | Yes |
Apply this matrix consistently across every reader-facing navigation and linking surface.
2. Documentation type is a separate concern
Section titled “2. Documentation type is a separate concern”docType classifies the purpose of a page. It does not control publication or reader visibility.
Supported values are:
docType: tutorialdocType: guidedocType: referencedocType: conceptdocType: troubleshootingdocType: overviewdocType: faqThe content schema defines the field as:
docType: z .enum([ "tutorial", "guide", "reference", "concept", "troubleshooting", "overview", "faq", ]) .optional()3. Central publication resolver
Section titled “3. Central publication resolver”The central visibility implementation is src/navigation/publication.js. It is responsible for:
- loading the Astro
docscontent collection - associating registered Lowgile routes with documentation entries
- reading each entry’s
statusandreleasevalues - normalizing route paths
- handling routes that contain fragments or query parameters
- exposing route- and href-based visibility helpers
- detecting broken internal route-to-content mappings
The primary public helpers are:
isRouteVisible(routeName)isHrefVisible(href)Both helpers ultimately apply the same condition:
publication.status === "published" &&publication.release === truePath normalization
Section titled “Path normalization”Routes may include fragments such as:
/platform-concepts/application-design/screen-concepts/#screen-variablesThese routes must resolve to the publication state of the underlying documentation page. Path normalization therefore removes:
- URL fragments
- query parameters
- trailing slashes
- a trailing
/index
Conceptually:
function normalizePath(path) { if (!path) return path;
return path .split("#")[0] .split("?")[0] .replace(/\/+$/, "") .replace(/\/index$/, "");}This allows a section-level route such as #screen-variables to inherit the visibility metadata of its parent MDX document.
Fail-closed internal route handling
Section titled “Fail-closed internal route handling”Registered internal routes must resolve to real documentation content. The resolver must not assume that a broken internal route is visible.
internal route→ content entry not found→ warning→ hiddenFor example, the resolver may emit:
Publication visibility: route "workflowAuditTrail" points to"/tutorials/workflow-task-screens/audit-trail/",but no matching docs content entry was found.This behavior prevents configuration mistakes from accidentally exposing content. Direct or external hrefs that are not registered in ROUTES remain allowed.
| Link type | Result |
|---|---|
| External or direct href | Allowed |
| Known internal route with visible content | Allowed |
| Known internal route with draft, review, or unreleased content | Hidden |
| Known internal route with no matching content | Warning and hidden |
4. Reader-facing integration points
Section titled “4. Reader-facing integration points”Url.astro
Section titled “Url.astro”src/components/navigation/Url.astro provides publication-aware internal links and external routes.
For internal routes, ‘Url.astro` resolves the target through the centralized publication system and determines its visibility automatically:
internal + visible → render <a>internal + hidden → render plain textexternal → render a normal external linkAuthors do not set publication state on the Url component. The component determines whether an internal target is reader-visibile from the target page’s status and release metadata.
Use Url directly inside normal prose. For example:
Creating the Module also creates a set of <Url name="defaultScreens">default Screens</Url>.If Default Screens is published and released, the Url component renders as a link.
If the target page is draft, under review, or unreleased, the same text remains in the sentence but renders without a hyperlink.
This plain-text fallback is appropriate when the sentence remains meaningful without access to the linked documnetation.
If the surrounding sentence or block only makes sense when the target documentation is available, use PublishedOnly.astro instead.
PublishedOnly.astro
Section titled “PublishedOnly.astro”Use src/components/navigation/PublishedOnly.astro when an entire block becomes meaningless if its target documentation is unavailable.
<PublishedOnly routeName="platformConceptsScreenConceptsScreenVariables"> <CalloutBubble type="note"> For more information, see <Url name="platformConceptsScreenConceptsScreenVariables"> Screen Variables </Url>. </CalloutBubble></PublishedOnly>When the target is visible, the block renders. When the target is hidden, the block does not render. This is preferable to a plain-text URL fallback when the surrounding content explicitly directs the reader to unavailable documentation.
ContentPageCard.astro
Section titled “ContentPageCard.astro”src/components/cards/ContentPageCard.astro hides a related-content card completely when its destination is not reader-visible. The component continues to apply existing card and sidebar presentation rules independently of publication visibility.
visible target → card rendersdraft, review, or unreleased → card does not render5. Overview-card generation
Section titled “5. Overview-card generation”The active overview implementation uses:
src/components/cards/OverviewCardGrid.astrosrc/components/cards/OverviewCardGridData.tssrc/components/cards/FeatureCard.astrosrc/components/cards/CardGrid.astroOverview cards consume the same isHrefVisible() rule. A child link is eligible only when it is reader-visible and overviewCard !== false. A root overview card requires overviewCard === true.
Publication state and overviewCard are separate conditions. For example:
status: publishedrelease: truecombined with:
overviewCard: falsemeans the page remains visible in the sidebar but is not promoted on the overview page. By contrast, status: published, release: false, and overviewCard: true still hides the page from both surfaces because publication visibility takes precedence.
If publication filtering removes every link from a generated overview card, the entire card is removed. Empty-card pruning prevents category cards with no usable destinations from appearing.
6. Sidebar visibility
Section titled “6. Sidebar visibility”The runtime sidebar uses the same reader-visibility rule:
status === "published"ANDrelease === trueThis replaces the previous use of sidebarDisplay as a visibility mechanism. Reader visibility now comes from frontmatter rather than duplicated sidebar configuration.
Structural sidebar groups do not need their own publication state. A group remains visible when at least one child is visible; if filtering removes all children, the group is removed.
7. Navigation presentation metadata
Section titled “7. Navigation presentation metadata”Publication metadata and navigation-presentation metadata remain separate. The sidebar-level presentation controls include:
overviewCardhomepageCardcollapsedoverviewDescriptionoverviewGroupoverviewGroupDescriptiondisplayThese properties determine where eligible content is presented. They do not determine whether the content is published.
overviewCard
Section titled “overviewCard”overviewCard controls whether a reader-visible item or structural group is promoted on a section overview page.
overviewCard: trueincludes an eligible item or group in generated overview cards.
overviewCard: falsekeeps a published document available in the sidebar but does not promote it on the overview page.
homepageCard
Section titled “homepageCard”homepageCard controls whether a top-level documentation section is promoted on the documentation homepage.
const tutorialsSidebar = { label: "Tutorials", homepageCard: true, // ...};Nested categories are normally promoted through their section overview rather than directly on the global homepage. The intended hierarchy is:
Homepage → Tutorials → Guides → Platform Concepts → Reference → Troubleshooting
Tutorials overview → Data Modeling → Platform Tools → AI & Data Extraction → ...display
Section titled “display”display: false remains an exceptional configuration-level mechanism for hiding an item everywhere. Do not use it as a substitute for normal content lifecycle or release management.
8. Backward compatibility
Section titled “8. Backward compatibility”The visibility model is deliberately backward compatible. Existing pages without publication metadata behave as if they contained:
status: publishedrelease: trueExisting documentation therefore remains visible unless it is explicitly changed. Teams can migrate content incrementally instead of updating every MDX file at once.
9. MDX component architecture
Section titled “9. MDX component architecture”Author-facing MDX components are registered centrally in src/components/mdx-components.js. src/plugins/remarkAutoImports.js consumes this registry instead of maintaining a duplicate component map. This makes mdx-components.js the single source of truth for components that documentation authors can invoke directly.
Do not register framework-only or internal implementation components. Examples include:
- Starlight overrides
CodeCell- internal diagram helpers
- internal card child components that MDX authors do not use directly
Astro and JSX responsibilities
Section titled “Astro and JSX responsibilities”Components that require publication-aware behavior use Astro because they need access to astro:content, asynchronous build-time logic, publication.js, or other Astro components.
Use Astro components for behavior that is:
- content-aware
- navigation-aware
- publication-aware
- evaluated at build time
Keep JSX components when they are purely presentational or interactive and do not require Astro-only functionality. The mixed architecture is intentional.
10. Route validation warnings
Section titled “10. Route validation warnings”The publication resolver exposes mismatches between internal-routes/index.js and actual content paths. For example, a registered route such as:
/reference/components/table-lists-components/does not match content whose actual path is:
/reference/components/tables-lists-components/Correct these mismatches because publication metadata is associated with content paths. The warning acts as both a publication safeguard and a route-integrity check.
11. Current pagination limitation
Section titled “11. Current pagination limitation”Starlight calculates Previous and Next pagination before the final runtime sidebar publication filter is applied. Filtering the sidebar therefore does not automatically guarantee that pagination skips draft, review, or unreleased documents.
Implement pagination filtering explicitly in the Starlight route middleware as a separate task. Do not hide this behavior inside the sidebar rendering component.
12. Authoring examples
Section titled “12. Authoring examples”Normal published documentation
Section titled “Normal published documentation”---title: Create Static Entitiesstatus: publishedrelease: true---This page is reader-visible.
Documentation still being written
Section titled “Documentation still being written”---title: Create Static Entitiesstatus: draftrelease: true---This page is hidden. release: true does not override a non-published editorial status.
Documentation under review
Section titled “Documentation under review”---title: Create Static Entitiesstatus: reviewrelease: true---This page is hidden.
Completed documentation for an unreleased feature
Section titled “Completed documentation for an unreleased feature”---title: Configure New AI Featurestatus: publishedrelease: false---This page is editorially complete but hidden from reader-facing navigation. When the product feature ships, change the value to release: true; no navigation configuration changes should be required.
13. Verification checklist
Section titled “13. Verification checklist”When changing publication behavior, verify all four representative metadata combinations:
published + truepublished + falsereview + truedraft + trueConfirm the expected behavior across:
- inline
Urllinks PublishedOnlyblocksContentPageCardcards- generated overview cards
- sidebar entries
- structural group pruning
Also verify that:
- external and direct hrefs continue to work
- broken internal route mappings generate warnings and remain hidden
- the production build succeeds
- pagination behavior is assessed separately until the known limitation is resolved
14. Central design principle
Section titled “14. Central design principle”The publication system has one authoritative reader-visibility rule:
status === "published"ANDrelease === trueEvery reader-facing surface must consume this rule through the centralized publication helpers instead of implementing its own interpretation. Navigation metadata such as overviewCard and homepageCard determines where visible content is promoted, not whether the content is published.