Scaffold a blog with BlogSite

By the end of this tutorial, a running BlogSite host titled "Scaffold Blog" serves a home listing, /archive, /blog/<slug>/, /tags/, /tags/<name>/, and /rss.xml — all from a single placeholder post under Content/Blog/.

AddBlogSite folds the host, layout, navigation, and styling into one call, configured for a site where the blog is the site; for what the template wires, where the wiring stops, and why DocSite and BlogSite can't share an app, read what the templates wire for you first.

Prerequisites

• .NET 10 SDK installed
• Completed Create your first Pennington site
• Completed Serve markdown through a Blazor catch-all (so Content/ already has at least one markdown file)

The stable .NET 10 SDK is all BlogSite needs — its package targets .NET 10, and you never write the union keyword that would call for a preview SDK. See the SDK and the union shim for when the .NET 11 beta is worth opting into.

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

1. Start from the bare Pennington host

The host you built in the getting-started tutorials calls AddPennington, registers content with AddMarkdownContent<DocFrontMatter>, mounts UsePennington, and routes through a Blazor @page "/{*Path}" catch-all (MarkdownPage.razor) that resolves each URL with IPageResolver to serve individual pages.

That host serves individual pages but nothing else: no home listing, no /archive, no /blog/<slug> pages, no /tags listings, no /rss.xml feed, and no MonorailCSS chrome. The next section brings all of that in with a single AddBlogSite call.

---
title: Hello world
description: A placeholder post so the scaffold has something to render. Tutorial 1.3.20 teaches the real BlogSiteFrontMatter fields.
date: 2026-04-13
author: Author Name
tags:
  - scaffold
---
  
This post exists so the bare BlogSite scaffold has at least one entry on the
home page and in the RSS feed. The next tutorial, **Author your first post
with `BlogSiteFrontMatter`**, walks through the full set of post front-matter
fields (tags, series, repository, section, redirectUrl, and more).

2. Wire AddBlogSite, UseBlogSite, and RunBlogSiteAsync

AddBlogSite is the BlogSite template's single registration call; it stands in for AddPennington plus the AddMarkdownContent<DocFrontMatter> line, wiring Pennington core, MonorailCSS, the Razor chrome, and the blog content services in one call. UseBlogSite mounts the middleware stack and Razor component routes; RunBlogSiteAsync dispatches between dev-serve and static-build.

var builder = WebApplication.CreateBuilder(args);
  
builder.Services.AddBlogSite(() => new BlogSiteOptions
{
    SiteTitle = "Scaffold Blog",
    SiteDescription = "A minimal BlogSite scaffold showing AddBlogSite, UseBlogSite, and RunBlogSiteAsync.",
    CanonicalBaseUrl = "https://example.com",
  
    ContentRootPath = "Content",
    BlogContentPath = "Blog",
    BlogBaseUrl = "/blog",
  
    AuthorName = "Author Name",
    AuthorBio = "Writing about software, tools, and the occasional side project.",
});
  
var app = builder.Build();
  
app.UseBlogSite(); 
  
await app.RunBlogSiteAsync(args); 

3. Verify every built-in route

With the post from section 1 in place and AddBlogSite wired, every route the template ships now responds. The placeholder post carries tags: [scaffold], so the tag routes have one entry to list.

The full route surface, including the paginated /archive/page/{n} and per-tag pages, is cataloged in Built-in BlogSite routes. The next tutorial expands the post to the full BlogSiteFrontMatter surface, adding tags, series, repository, sectionLabel, and redirectUrl.

Summary

• The bare AddPennington host gave way to AddBlogSite + UseBlogSite + RunBlogSiteAsync, and the full BlogSite chrome now renders.
• The core BlogSiteOptions surface — SiteTitle, SiteDescription, CanonicalBaseUrl, ContentRootPath, BlogContentPath, BlogBaseUrl, AuthorName, AuthorBio — is populated, and each field flows through to the rendered output.
• BlogSite binds posts through AddMarkdownContent<BlogSiteFrontMatter> (introduced in the next tutorial) and defaults content paths to Content/Blog served at /blog, which distinguishes it from the DocSite template's area-driven layout.
• Every built-in route the template ships responds: /, /archive, /blog/<slug>, /tags, /tags/<name>, and /rss.xml.