This documentation is also published as Markdown for efficient machine reading: the whole site is indexed at /llms.txt, and every page has a clean Markdown copy under /_llms/. These are generated from the same source and cost far fewer tokens to read than this rendered HTML.

Skip to main content Skip to navigation
Under the Hood

The Pennington mental model

A short map of the host, content sources, rendering pipeline, response pipeline, and DocSite/BlogSite templates before you dive into the deeper architecture pages.

Pennington is easiest to understand as a normal ASP.NET app with a content engine inside it. You run the app while writing, and you ask the same app to build static files when publishing.

That single idea explains most of the project:

  • The host is ASP.NET. Program.cs owns dependency injection, middleware order, Razor components, and any custom endpoints.
  • Content sources discover pages. Markdown folders, Razor pages, redirects, generated API reference, taxonomy pages, and custom services all report routes into the same site model.
  • The content pipeline turns discovered content into rendered content. A page moves from "I know where it is" to "I parsed its front matter" to "I rendered its HTML"; failures travel through the same pipeline so the build report can name them.
  • The response pipeline finishes the HTML. Cross-references, locale prefixes, base URLs, live reload, diagnostics, and other response processors run against the actual HTTP response.
  • Build mode crawls the host. dotnet run serves through Kestrel; dotnet run -- build starts the same app on an in-process test server, requests every discovered route, and writes the responses to disk.

The layers

Pennington

Pennington is the lower-level engine. It gives you content discovery, markdown parsing, rendering, route resolution, response processing, diagnostics, search artifacts, feeds, and static output. You bring the site shell: layout, navigation markup, styling, and any app-specific endpoints.

Start here when you are embedding content into an existing ASP.NET app, building a custom layout, or mixing several kinds of content that do not fit a stock documentation or blog template. The first getting-started arc walks this path: Create your first Pennington site.

Pennington.DocSite

Pennington.DocSite is a pre-assembled documentation site on top of the engine. One AddDocSite call wires the engine, markdown content, DocSite layout, sidebar navigation, search, MonorailCSS styling, SPA navigation, feeds, and static build behavior.

Start here for a conventional documentation site. You can still customize options and add extension points, but the template owns the article-shaped layout. The scaffold tutorial starts here: Scaffold a documentation site with DocSite.

Pennington.BlogSite

Pennington.BlogSite is the same idea for a blog-first site. It is a template, not a separate engine: the underlying runtime is still Pennington content discovery plus the shared ASP.NET request pipeline.

Use it when the blog is the site. If you want a blog alongside documentation, use DocSite's built-in blog folder instead of combining DocSite and BlogSite in the same app.

Pennington.UI

Pennington.UI is the Razor component library — table-of-contents and outline navigation, breadcrumbs, pagination, cards, badges, code blocks, callouts, the search modal, and the client-side SPA navigation script. DocSite and BlogSite reference it for you and pre-register the markdown-facing components, so you rarely call it directly on a template.

You meet it the moment you go bare-engine. AddPennington does not assume a layout, so a custom shell that wants the same navigation chrome or wants to drop components into markdown pulls these in itself. The components and their parameters are catalogued in the UI reference: Content components, Navigation components, and Utility components. To use them inside markdown, see Drop a Razor component into a markdown page.

Pennington.TreeSitter

Pennington.TreeSitter is the optional code-fragment extractor. It powers the :symbol fence — addressing a member by its name path so a code block shows one method instead of a whole file — across the languages tree-sitter parses.

It is opt-in: register it with AddTreeSitter and point ContentRoot at the root that holds the source you want to fence. Nothing else changes, so you add it only when a site embeds live source. The recipes live in Embed focused code samples.

Terms you will see

Term Meaning
Host The ASP.NET app that registers Pennington and handles requests.
Content source A service that discovers routes and records for pages or generated artifacts.
Front matter Typed metadata parsed from the YAML block at the top of a markdown file.
Route The URL and output-file mapping for a page or endpoint.
Xref A symbolic link such as <xref:tutorials.docsite.scaffold> that resolves to the current route for a page or API member.
Response processor A hook that rewrites the HTTP response before it reaches the browser or static output folder.
Build report The diagnostics summary printed by dotnet run -- build.