Author a documentation page with DocFrontMatter

By the end of this tutorial the DocSite has a guides/authoring.md page showing a fully-populated front-matter block, a rendered [!NOTE] alert, and a three-panel tabbed code group — with the outline nav on the right listing every ## heading on the page.

This tutorial covers populating DocSiteFrontMatter, reaching for Pennington's GitHub-style alerts, and grouping adjacent fenced code blocks into a tabbed component without writing a single line of Razor or JavaScript.

Prerequisites

.NET 11 SDK installed
Completed Scaffold a DocSite (or have an equivalent single-area DocSite project ready with a Guides area pointed at Content/guides/)

The finished code for this tutorial lives in examples/DocSiteAuthorExample.

1. Populate `DocSiteFrontMatter`

Let's start with the metadata block that drives the sidebar entry, the <title>, the meta description, and the tag chips. Stage 1 is front matter plus a single heading — the skeleton every later stage builds on.

1
Create Content/guides/authoring.md

In the Guides area folder (Content/guides/), create a new file named authoring.md and leave it empty for now. The next step fills it in.
2
Paste the stage-1 markdown

Copy the block below verbatim into authoring.md. The five keys — title, description, tags, sectionLabel, order — are the ones DocSiteFrontMatter reads to build the sidebar, meta tags, and tag chips. Everything below the closing --- is the page body.
```
---
title: Authoring a doc page
description: Populate DocSiteFrontMatter, add an alert, and group code samples into tabs.
tags:
  - authoring
  - front-matter
  - markdown
sectionLabel: Guides
order: 20
---
  
# Authoring a doc page
  
This page demonstrates every authoring surface a typical DocSite page uses.
```
sectionLabel controls the prev/next breadcrumb label shown beneath the page header; it's not what groups pages into the sidebar (subfolder layout does that). order decides where this page sits relative to its siblings.

Checkpoint — Stage-1 page renders

Run dotnet run from the project folder and visit http://localhost:5000/guides/authoring.
The h1 reads "Authoring a doc page", the description renders as meta, and a sidebar entry labelled "Authoring a doc page" appears under the Guides area.
The outline nav on the right is empty — there are no ## headings yet. That changes in unit 2.

2. Add a GitHub-style alert

Pennington recognises the GitHub alert syntax: a block quote whose first line is [!KIND]. Adding one produces a coloured callout and — because the callout introduces a ## heading above it — the first outline-nav entry.

Replace the file body with the stage-2 markdown

Swap the current contents of authoring.md for the block below. It keeps the same front matter and adds a ## Callouts section containing a [!NOTE] alert.

---
title: Authoring a doc page
description: Populate DocSiteFrontMatter, add an alert, and group code samples into tabs.
tags:
  - authoring
  - front-matter
  - markdown
sectionLabel: Guides
order: 20
---
  
# Authoring a doc page
  
## Callouts
  
> [!NOTE]
> Alerts render with a coloured left border and an icon matching the kind.
> Supported kinds include `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and
> `CAUTION`.

The supported kinds are NOTE, TIP, IMPORTANT, WARNING, and CAUTION. Pennington's CustomAlertInlineParser rewrites the surrounding quote block into a markdown-alert container so CSS can style it.

Checkpoint — Alert and first outline entry

Reload http://localhost:5000/guides/authoring.
The [!NOTE] block now renders as a blue-bordered callout with an info icon — not a plain block quote.
The outline nav on the right shows a single entry, "Callouts", linking to #callouts.

3. Add a tabbed code group

Marking two or more adjacent fenced code blocks with tabs=true and a title="…" fence argument tells Pennington's TabbedCodeBlockRenderer to group them into a single ARIA tablist. The tab labels come from each block's title.

Replace the file body with the stage-3 markdown

Paste the block below over the current contents of authoring.md. It keeps the front matter and alert from stage 2 and adds a ## Tabbed code groups section with three adjacent fenced blocks.

---
title: Authoring a doc page
description: Populate DocSiteFrontMatter, add an alert, and group code samples into tabs.
tags:
  - authoring
  - front-matter
  - markdown
sectionLabel: Guides
order: 20
---
  
# Authoring a doc page
  
## Callouts
  
> [!NOTE]
> Alerts render with a coloured left border and an icon matching the kind.
  
## Tabbed code groups
  
```bash tabs=true title="dotnet CLI"
dotnet add package Pennington
```
  
```powershell tabs=true title="PowerShell"
Install-Package Pennington
```
  
```xml tabs=true title="csproj"
<PackageReference Include="Pennington" Version="*" />
```

Each fence still gets normal syntax highlighting based on its language (bash, powershell, xml). The tabs=true flag and title="…" label are what tell the tabbed renderer these three blocks belong together — drop either one and the blocks render independently.

Checkpoint — Tabs render and outline nav populates

Reload http://localhost:5000/guides/authoring.
The three fenced blocks under "Tabbed code groups" render as one component with three selectable tabs ("dotnet CLI", "PowerShell", "csproj"); clicking a tab swaps the visible code.
The outline nav on the right shows two entries — "Callouts" and "Tabbed code groups" — each linking to its heading anchor.

Summary

Every key DocSiteFrontMatter reads — title, description, tags, sectionLabel, order — flows through to the sidebar, meta description, and prev/next label.
A GitHub-style [!NOTE] alert goes through Pennington's CustomAlertInlineParser and renders as a styled callout.
Three adjacent fenced code blocks with tabs=true and title="…" become a single tabbed component.
The outline nav populates automatically from the page's ## headings — no manual nav wiring.