Organize content with sections and areas

using Pennington.DocSite;
  
var builder = WebApplication.CreateBuilder(args);
  
// Same DocSite host shape as apps #4 and #5 — the focus here is on the
// *structure* of `Content/`. Two areas, each broken into two subfolder-backed
// sections. `NavigationBuilder` (inside `MainLayout`) turns the discovered
// flat TOC list into a grouped sidebar: each subfolder under an area becomes
// a non-navigable section header, and the pages inside sort by their front
// matter `order:` (tiebreaker: title).
builder.Services.AddDocSite(() => new DocSiteOptions
{
    SiteTitle = "Sections Docs",
    Description = "Structure Content/ into areas and sections using subfolders, section, and order front matter.",
    GitHubUrl = "https://github.com/usepennington/pennington",
    HeaderContent = """<a href="/">Sections Docs</a>""",
    FooterContent = """<footer class="mt-16 py-8 text-center text-sm text-base-500">Built with Pennington DocSite.</footer>""",
  
    // Two areas bound to two top-level content folders. The sidebar renders
    // an area selector above the per-area TOC; each area's TOC is grouped
    // by subfolder (sections "Getting Started" / "Advanced" under guides,
    // "Core Api" / "Extensions" under reference).
    Areas =
    [
        new ContentArea("Guides", "guides"),
        new ContentArea("Reference", "reference"),
    ],
});
  
var app = builder.Build();
  
app.UseDocSite();
  
await app.RunDocSiteAsync(args);

"""
        ---
        title: Install Pennington
        description: Add the Pennington package to a new or existing ASP.NET project.
        ---
  
        # Install Pennington
  
        The first thing every new Pennington site needs is the package itself.
        """

"""
        ---
        title: Install Pennington
        description: Add the Pennington package to a new or existing ASP.NET project.
        sectionLabel: Getting Started
        order: 10
        ---
  
        # Install Pennington
  
        The first thing every new Pennington site needs is the package itself.
        """

---
title: Guides
description: Walk-throughs for getting productive with Pennington, grouped by skill level.
sectionLabel: Guides
order: 0
---
  
# Guides
  
Welcome to the **Guides** area. The sidebar groups every page in this area by
the subfolder it lives in — *Getting Started* collects the first three pages
you want to read, *Advanced* holds the deeper material. Within each group,
pages are ordered by the `order:` front-matter key.
  
Pick a page from the sidebar to jump in.

---
title: Create your first project
description: Wire AddPennington and UsePennington into Program.cs and drop in a markdown page.
sectionLabel: Getting Started
order: 20
---
  
# Create your first project
  
With the package installed, the smallest useful site is two lines of
registration and one markdown file on disk.
  
## Program.cs
  
```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPennington();
  
var app = builder.Build();
app.UsePennington();
await app.RunOrBuildAsync(args);
```
  
## Drop in a page
  
Create `Content/index.md` with a `title:` front-matter key and a body. Run
`dotnet run` and the page is served from `/` with hot reload on file change.
  
The next guide covers the handful of options you will reach for first.

---
title: Configure your site
description: Tour the PenningtonOptions knobs you will reach for on day one.
sectionLabel: Getting Started
order: 30
---
  
# Configure your site
  
`AddPennington` accepts a configuration callback that lets you tune the
content root, URL style, and a handful of feature toggles without leaving
`Program.cs`.
  
## Point at a content folder
  
By default Pennington reads from `Content/` next to your project. Override
the path when your content lives elsewhere in the repo or ships from an
embedded resource.
  
## Change the URL style
  
`LowercaseUrls` and `AppendTrailingSlash` control the shape of every
generated link. Pick a style early — changing it later invalidates existing
inbound links unless you pair the change with redirect front matter.
  
The next area — *Advanced* — covers layout overrides and the response
pipeline.

---
title: Swap in a custom layout
description: Override the default DocSite layout with your own Razor component.
sectionLabel: Advanced
order: 40
---
  
# Swap in a custom layout
  
DocSite ships with a sensible default layout, but every surface is a plain
Razor component. When you need a different header, footer, or body grid,
register your layout after `AddDocSite` and it takes precedence.
  
## Replace the main layout
  
Pass `AdditionalRoutingAssemblies` a reference to the assembly that holds
your `MyLayout.razor`, then mark it with the same `@layout`/`@inherits`
shape DocSite's `MainLayout` uses.
  
## Keep the sidebar or write your own
  
The easiest path is to keep `AreaNavigation` and `TableOfContentsNavigation`
inside your custom layout so sidebar grouping still works exactly as this
tutorial describes. The harder path — writing a bespoke nav — is covered
in a later how-to.

---
title: Hook into the response pipeline
description: Intercept rendered HTML before it reaches the browser with IResponseProcessor.
sectionLabel: Advanced
order: 50
---
  
# Hook into the response pipeline
  
Every rendered page flows through a response pipeline before hitting the
wire. Register an `IResponseProcessor` to mutate the HTML — add a feedback
widget, rewrite anchor IDs, or inject analytics — without touching the
markdown.
  
## Register a processor
  
```csharp
builder.Services.AddSingleton<IResponseProcessor, MyProcessor>();
```
  
Processors run in `Order` ascending. Override `ShouldProcess` to scope the
work to particular routes, content types, or request metadata.
  
## Where this fits vs islands
  
Response processors mutate the already-rendered page; islands let you hand
a region of the DOM off to a Razor component that rehydrates on the
client. Reach for a processor when the change is purely HTML; reach for an
island when you need interactive state.

---
title: Reference
description: API surface for the Pennington library, split into core and extension packages.
sectionLabel: Reference
order: 0
---
  
# Reference
  
The **Reference** area mirrors the package structure: *Core API* covers the
types in `Pennington` itself, *Extensions* covers the optional surface
(Markdig extensions, content services). Page order inside each section
matches the order you are likely to discover the types while building a
site.
  
Pick a page from the sidebar to inspect a specific surface.

---
title: PenningtonOptions
description: Core configuration surface handed to AddPennington.
sectionLabel: Core API
order: 10
---
  
# PenningtonOptions
  
`PenningtonOptions` is the record the configuration callback on
`AddPennington` mutates. It holds a handful of knobs that apply to every
page in the site regardless of content source.
  
## Keys worth knowing
  
- `ContentRootPath` — folder (or embedded-resource root) content is
  discovered from.
- `LowercaseUrls` — whether to force every generated URL to lowercase.
- `AppendTrailingSlash` — pick slash vs no-slash for clean URLs.
- `UrlStyle` — `Clean` (folder/index.html) or `Extension` (filename.html).
  
Every option has a sensible default; populate only the ones you need to
deviate from.

---
title: ContentPipeline
description: The discovery/parse/render pipeline every content source flows through.
sectionLabel: Core API
order: 20
---
  
# ContentPipeline
  
`ContentPipeline` is the assembly line `IContentService` implementations
feed into. Each source yields `DiscoveredItem`s, the pipeline parses them
into `ParsedItem`s via `IContentParser`, and finally renders them into
`RenderedItem`s via `IContentRenderer`.
  
## The three stages
  
1. **Discover** — each registered `IContentService` walks its source (disk,
   Razor pages, a JSON feed, whatever) and emits `DiscoveredItem` unions.
2. **Parse** — the matching `IContentParser` reads the item, separates
   front matter from body, and produces a `ParsedItem`.
3. **Render** — `IContentRenderer` turns the parsed body into HTML (plus
   an outline of headings and any diagnostics).
  
Custom parsers and renderers plug into the same pipeline — see the
*Extensions* section in the sidebar for how to write one.

---
title: Markdown extensions
description: The Markdig extensions Pennington ships with — alerts, tabbed code, highlighting.
sectionLabel: Extensions
order: 30
---
  
# Markdown extensions
  
Pennington configures Markdig with a curated set of extensions that light
up the authoring syntax the tutorials lean on.
  
## What ships in the box
  
- **Alerts** — GitHub-flavoured block quotes (`> [!NOTE]`, `TIP`,
  `IMPORTANT`, `WARNING`, `CAUTION`).
- **Tabbed code groups** — two or more adjacent fenced blocks with
  `tabs=true title="…"`.
- **Syntax highlighting** — TextMate grammars, ANSI shell output, and
  optional Roslyn-backed highlighting.
-** Code annotations** — `//` inline markers.
  
Registering your own extension is covered in the *Hook into the response
pipeline* guide's companion how-to.

---
title: Custom content services
description: Teach Pennington a new content source by implementing IContentService.
sectionLabel: Extensions
order: 40
---
  
# Custom content services
  
`IContentService` is the extension point for loading content from anything
that isn't plain markdown — a JSON feed, a database, a remote API, an
embedded resource. Register an implementation and the pipeline treats its
items exactly like every other source.
  
## The four methods
  
- `DiscoverAsync()` — yield a `DiscoveredItem` per logical page.
- `GetContentTocEntriesAsync()` — flat list of TOC entries with title,
  order, and hierarchy parts.
- `GetCrossReferencesAsync()` — any `uid`-to-route mappings you want the
  xref resolver to see.
- `GetContentToCopyAsync()` — assets the static-build step should copy
  alongside the rendered HTML.
  
Implementations live next to `MarkdownContentService` in the DI container
and are iterated in registration order.