Table of Contents

Metadata reference

Last updated:

Manual pages in strombetta/helium-docs use YAML front matter to identify their purpose, ownership domain, applicable version, support state, and review status. This page defines the human-readable metadata contract. Automated schema validation is implemented separately.

Use only documented fields and controlled values. Add a new value only when a concrete navigation, search, validation, ownership, or release requirement needs it.

Minimum front matter

Every published manual page uses these fields:

---
title: Protect ASP.NET Core endpoints
description: Protect application endpoints by applying Helium authorization policies.
content_type: how-to
area: authorization
version: 1.x
status: stable
last_reviewed: 2026-07-30
---

Required fields

title

The page title used by navigation, search, and HTML metadata.

Requirements:

  • normally matches the page H1 exactly;
  • uses sentence case;
  • describes the subject or task clearly;
  • starts with a verb for how-to pages;
  • avoids repeating Helium when the site context is sufficient.

description

A short description used in search results, cards, and HTML metadata.

Requirements:

  • explains what the reader can do or understand;
  • remains meaningful outside the local TOC context;
  • does not repeat the title without adding information;
  • uses one concise sentence in most cases;
  • avoids promotional or unsupported claims.

content_type

Identifies the page's dominant editorial purpose.

Allowed values:

Value Purpose
index Orient readers within a section or capability.
overview Explain what an area provides and when it applies.
concept Explain a model, relationship, lifecycle, invariant, or behavior.
tutorial Teach through a complete and ordered scenario.
how-to Show how to complete one specific task.
reference Provide exact and systematically structured information.
troubleshooting Diagnose a symptom and resolve it using evidence.
release Explain release changes, compatibility, deprecations, or upgrades.

A page has one content_type. Supporting sections do not create additional types.

area

Identifies the primary functional or documentation domain that owns the page.

Initial allowed values:

Group Values
Product and onboarding product, getting-started, architecture
Application capabilities configuration, identity, onboarding, organizations, authorization, billing, entitlements, communications
Extension and operation extensibility, persistence, durable-processing, hosting, deployment, diagnostics, security, testing, performance
Documentation systems troubleshooting, compatibility, api, contributing

Select one primary area even when a page links to several domains. Cross-domain relationships belong in the page content and related links.

version

Identifies the documentation line to which the page applies.

Initial allowed values:

Value Meaning
all Version-independent documentation, primarily contribution guidance or stable general concepts.
1.x Applies to the Helium 1.x documentation line.
preview Applies only to unreleased or preview behavior.

Do not use patch versions for ordinary pages. Add a new version value only when that documentation line exists.

status

Identifies the support state of the documented feature or behavior.

Value Meaning
stable Supported for ordinary use in the applicable release line.
preview Available for evaluation and subject to change.
deprecated Still available but scheduled for replacement or removal.
legacy Maintained primarily for compatibility with an older supported path.
unsupported Documented for clarity but outside the supported product scope.

status does not represent whether the document is a draft or has completed editorial review.

last_reviewed

The date on which a responsible reviewer last verified the page against the applicable framework behavior and documentation standards.

Format:

last_reviewed: YYYY-MM-DD

Do not update this field for spelling changes, formatting-only changes, or automated migrations that do not include substantive technical review.

Conditional fields

uid

A stable logical identifier that can survive file moves.

uid: authorization-protect-endpoints

Use lowercase words separated by hyphens. Do not include the content type, version, or complete file path. UIDs must be unique.

UIDs are initially recommended for:

  • fundamental concepts;
  • manual reference pages;
  • pages used by learning paths;
  • highly linked task pages.

level

Use primarily for tutorials, learning paths, and selected how-to guides.

Allowed values:

Value Meaning
beginner Requires no previous Helium experience and follows the primary supported path.
intermediate Assumes completion of Getting started and combines several Helium concepts.
advanced Requires detailed knowledge of extension, architecture, operation, or compatibility boundaries.

Level does not determine TOC placement.

audience

Identifies an audience when that distinction changes prerequisites, terminology, or task framing.

Initial allowed values:

  • developer;
  • technical-lead;
  • operator;
  • contributor.

Example:

audience:
  - developer
  - operator

Do not add audience metadata merely because several roles might read the page.

keywords

Adds search terms and established synonyms that do not appear naturally in the title or description.

keywords:
  - tenant context
  - current organization

Do not repeat common terms already used throughout the page or add broad SEO keywords.

owner

Identifies a stable team, functional area, or repository alias responsible for review.

owner: authorization

Prefer stable ownership identifiers over individual names.

source

Identifies framework artifacts closely associated with the page.

source:
  - Trombetta.SaaS
  - Trombetta.SaaS.Hosting.AspNetCore

Use this field when it supports ownership, drift detection, or automated review routing. It is not required for general overview content.

Presentation fields

Use presentation fields only when the standard article layout does not fit the page. They begin with an underscore because they are interpreted by DocFX rather than by the Helium content model.

_layout

Selects a supported modern-template layout.

Value Use
landing Section or product landing pages that do not use the standard three-column article layout.
chromeless Exceptional pages that require no ordinary site chrome.

The documentation homepage uses landing. Ordinary articles must not set this field.

Layout controls

The following Boolean fields suppress standard navigation elements for exceptional pages:

Field Effect
_disableToc Hides the left table of contents.
_disableAffix Hides the right In this article rail.
_disableBreadcrumb Hides the breadcrumb.
_disableContribution Hides the built-in edit action.
_disableNextArticle Hides previous and next article links.
_disableTocFilter Hides the local TOC filter.
_noindex Excludes the page from DocFX search results.

Do not use these fields to work around an incorrect TOC placement or poor page structure. The homepage may disable article-only controls; ordinary pages inherit the global navigation behavior.