--- title: The Pennington mental model description: "A short map of the host, content sources, rendering pipeline, response pipeline, and DocSite/BlogSite templates before you dive into the deeper architecture pages." canonical_url: https://usepennington.net/explanation/core/mental-model/ sidecar_url: https://usepennington.net/explanation/core/mental-model.md content_hash: sha256:497e2a9bc9a1f158397e6335df4924e0fe55f286872c350a0815cd79baecff73 tokens: 1574 uid: explanation.core.mental-model reading_time_minutes: 4 --- 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](https://usepennington.net/tutorials/getting-started/first-site.md). ### `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](https://usepennington.net/tutorials/docsite/scaffold.md). ### `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](https://usepennington.net/reference/ui/content.md), [Navigation components](https://usepennington.net/reference/ui/navigation.md), and [Utility components](https://usepennington.net/reference/ui/utility.md). To use them inside markdown, see [Drop a Razor component into a markdown page](https://usepennington.net/how-to/rich-content/ui-components-in-markdown.md). ### `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](https://usepennington.net/how-to/code-samples/focused-code-samples.md). ## 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 `` 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`. ## What to read next - Build a bare host: [Create your first Pennington site](https://usepennington.net/tutorials/getting-started/first-site.md) - Scaffold a documentation site: [Scaffold a documentation site with DocSite](https://usepennington.net/tutorials/docsite/scaffold.md) - Understand why dev and build share one app: [Dev mode and build mode share one code path](https://usepennington.net/explanation/core/dev-vs-build.md) - Understand the content pipeline internals: [The content pipeline and union types](https://usepennington.net/explanation/core/content-pipeline.md) - See what DocSite and BlogSite wire for you: [What the DocSite and BlogSite templates wire for you](https://usepennington.net/explanation/positioning/docsite-positioning.md) [Next The content pipeline and union types](https://usepennington.net/explanation/core/content-pipeline.md)