Skip to content

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"
AND
release === true

A document is reader-visible only when it is both editorially published and released.

status represents the editorial state of a documentation page. Supported values are:

status: draft
status: review
status: published

The 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 determines whether the documentation may be exposed to readers. Supported values are:

release: true
release: false

The 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: published
release: false

This combination means that the documentation is complete but must remain hidden until the related product feature is released.

StatusReleaseReader-visible
drafttrueNo
draftfalseNo
reviewtrueNo
reviewfalseNo
publishedfalseNo
publishedtrueYes

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: tutorial
docType: guide
docType: reference
docType: concept
docType: troubleshooting
docType: overview
docType: faq

The content schema defines the field as:

docType: z
.enum([
"tutorial",
"guide",
"reference",
"concept",
"troubleshooting",
"overview",
"faq",
])
.optional()

The central visibility implementation is src/navigation/publication.js. It is responsible for:

  • loading the Astro docs content collection
  • associating registered Lowgile routes with documentation entries
  • reading each entry’s status and release values
  • 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 === true

Routes may include fragments such as:

/platform-concepts/application-design/screen-concepts/#screen-variables

These 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.

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
→ hidden

For 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 typeResult
External or direct hrefAllowed
Known internal route with visible contentAllowed
Known internal route with draft, review, or unreleased contentHidden
Known internal route with no matching contentWarning and hidden

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 text
external → render a normal external link

Authors 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.

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.

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 renders
draft, review, or unreleased → card does not render

The active overview implementation uses:

src/components/cards/OverviewCardGrid.astro
src/components/cards/OverviewCardGridData.ts
src/components/cards/FeatureCard.astro
src/components/cards/CardGrid.astro

Overview 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: published
release: true

combined with:

overviewCard: false

means 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.

The runtime sidebar uses the same reader-visibility rule:

status === "published"
AND
release === true

This 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.

Publication metadata and navigation-presentation metadata remain separate. The sidebar-level presentation controls include:

overviewCard
homepageCard
collapsed
overviewDescription
overviewGroup
overviewGroupDescription
display

These properties determine where eligible content is presented. They do not determine whether the content is published.

overviewCard controls whether a reader-visible item or structural group is promoted on a section overview page.

overviewCard: true

includes an eligible item or group in generated overview cards.

overviewCard: false

keeps a published document available in the sidebar but does not promote it on the overview page.

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: 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.

The visibility model is deliberately backward compatible. Existing pages without publication metadata behave as if they contained:

status: published
release: true

Existing documentation therefore remains visible unless it is explicitly changed. Teams can migrate content incrementally instead of updating every MDX file at once.

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

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.

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.

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.

---
title: Create Static Entities
status: published
release: true
---

This page is reader-visible.

---
title: Create Static Entities
status: draft
release: true
---

This page is hidden. release: true does not override a non-published editorial status.

---
title: Create Static Entities
status: review
release: true
---

This page is hidden.

Completed documentation for an unreleased feature

Section titled “Completed documentation for an unreleased feature”
---
title: Configure New AI Feature
status: published
release: 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.

When changing publication behavior, verify all four representative metadata combinations:

published + true
published + false
review + true
draft + true

Confirm the expected behavior across:

  • inline Url links
  • PublishedOnly blocks
  • ContentPageCard cards
  • 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

The publication system has one authoritative reader-visibility rule:

status === "published"
AND
release === true

Every 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.