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 at the same URL with .md appended. 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
Getting Started

Add a blog to your documentation site

Drop a Content/blog folder into a DocSite and watch the blog index, post pages, browse-by-tag pages, and RSS feed light up — no Program.cs changes.

By the end of this tutorial the DocSite at http://localhost:5000/ carries a Blog link in its header, a /blog index listing two posts newest-first, post pages with a date and byline, browse-by-tag pages, and an RSS feed at /rss.xml.

The blog activates from content alone — a folder named blog under Content/. There is no Program.cs change anywhere in this tutorial; every step is a markdown file.

Prerequisites

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

1. Write your first post

A DocSite turns on its blog when it finds a folder named blog under Content/. Create that folder, drop one post into it, and the blog appears.

1

Create Content/blog/launching-the-docs.md

Add a blog folder under Content/, alongside your area folders, and create launching-the-docs.md inside it. The filename minus .md becomes the post's URL slug, so this post serves at /blog/launching-the-docs.

Note

The folder must be named exactly blog, in lowercase. On a case-sensitive filesystem Blog or blogs is not detected.

2

Paste in the post

Paste the markdown below. The four front-matter fields are the ones every post uses: title is the post heading and link label, description is the summary shown on the blog index, author is the byline, and date is the publication date.

markdown 
---
title: Launching the Harbor docs
description: The Harbor documentation site is live, and it now has a blog.
author: Dana Reyes
date: 2026-05-08
---
  
Harbor's documentation has a new home. Alongside the guides, this blog will
carry release notes, design notes, and the occasional field report.
  
## Why a blog
  
Guides explain how Harbor works today. A blog is the place for what changed
and why — the running story behind the tool.
3

Run the host

bash 
dotnet run

Open http://localhost:5000/.

Checkpoint

  • A Blog link appears in the site header, beside the theme toggle.
  • http://localhost:5000/blog lists one post — Launching the Harbor docs — with its date and description.
  • http://localhost:5000/blog/launching-the-docs renders the post body under its title, with the By Dana Reyes byline.

2. Add a second post

The blog index orders posts by date, newest first. Add a second, more recent post and watch it take the top slot.

1

Create Content/blog/whats-next.md

Add a second file in the blog folder with the markdown below. Its date — 2026-05-15 — is a week after the first post.

markdown 
---
title: What's next for Harbor
description: A look at the features on the Harbor roadmap for the next release.
author: Dana Reyes
date: 2026-05-15
---
  
The docs are live, so here is where Harbor goes next.
  
## On the roadmap
  
- Faster incremental builds.
- A watch mode that reloads on content changes.
- A plugin hook for custom output formats.
2

Reload the blog index

A markdown edit needs no restart — the host watches Content/. Save the file and reload http://localhost:5000/blog.

Checkpoint

  • http://localhost:5000/blog now lists two posts.
  • What's next for Harbor sits above Launching the Harbor docs — the newer date puts it first.

3. Tag your posts and find the feed

A tags list on a post adds it to browse-by-tag pages. Tag both posts, then look at the feed the blog has been publishing all along.

1

Add tags to the first post

Add a tags block to launching-the-docs.md. The file now reads:

markdown 
---
title: Launching the Harbor docs
description: The Harbor documentation site is live, and it now has a blog.
author: Dana Reyes
date: 2026-05-08
tags:
  - announcements
  - docs
---
  
Harbor's documentation has a new home. Alongside the guides, this blog will
carry release notes, design notes, and the occasional field report.
  
## Why a blog
  
Guides explain how Harbor works today. A blog is the place for what changed
and why — the running story behind the tool.
2

Add tags to the second post

Give whats-next.md its own tags block. One tag, announcements, is shared with the first post.

markdown 
---
title: What's next for Harbor
description: A look at the features on the Harbor roadmap for the next release.
author: Dana Reyes
date: 2026-05-15
tags:
  - announcements
  - roadmap
---
  
The docs are live, so here is where Harbor goes next.
  
## On the roadmap
  
- Faster incremental builds.
- A watch mode that reloads on content changes.
- A plugin hook for custom output formats.
3

Reload and follow the tags

Save both files and reload http://localhost:5000/blog/launching-the-docs.

Checkpoint

  • The post page now lists its tags beneath the body — launching-the-docs shows announcements and docs as links.
  • Following a tag opens its page — http://localhost:5000/blog/tags/announcements lists both posts; /blog/tags/docs lists only the first.
  • The blog index carries a Browse by tag link to http://localhost:5000/blog/tags, which lists all three tags with their post counts — announcements (2), docs (1), and roadmap (1).

Now look at the feed the blog has been publishing since your first post.

Checkpoint

  • http://localhost:5000/rss.xml is a valid RSS feed — a <channel> with the site title and two <item> elements whose <title>, <description>, <pubDate>, and <author> come from the front matter. The <link> URLs are relative to your site root, since no CanonicalBaseUrl is set; set DocSiteOptions.CanonicalBaseUrl to make them absolute.
  • Run dotnet run -- build — the static build writes blog/index.html, the two post pages, the blog/tags/ pages, and rss.xml into output/.

Every front-matter field you wrote into those posts is parsed into a BlogPostFrontMatter record, the type a DocSite binds for content under the blog folder.

Summary

  • A folder named blog under Content/ is the whole switch — AddDocSite finds it at startup and turns on the blog index, post pages, tag pages, the RSS feed, and the header link.
  • Each BlogPostFrontMatter field drives a surface: title, description, and date for the index; author for the byline and RSS; tags for the /blog/tags/ pages.
  • Posts sort newest-first by date.
  • /rss.xml is generated automatically; its <link> URLs are relative until you set DocSiteOptions.CanonicalBaseUrl.
  • None of it needed a Program.cs change — the blog is pure content.

That rounds out the Getting Started with DocSite series. To go further, the Beyond the Basics tutorials build on this same host: add a second locale to your site and author a custom Razor component for markdown.