Anudwigna.StaticMarkdownEngine 1.0.0-beta.2

Anudwigna.StaticMarkdownEngine

Beta release — Core API is stable. Feedback welcome before 1.0.0 GA.

A zero-configuration .NET library that turns a folder of Markdown files with YAML front matter into a fully-routed ASP.NET Core website — with a built-in content query API inspired by Nuxt Content.

Table of Contents

• Features
• How It Works
• Requirements
• Installation
• Quick Start
• Content API
• Configuration Reference
• YAML Front Matter Reference
• Tag Helper Reference
• CLI Reference
• API Reference
• Dependencies
• License

Features

How It Works

The library distinguishes two types of Markdown content:

myapp/
├── input/            ← static pages (about, docs, etc.)
│   ├── index.md      →  output/index.html      →  GET /
│   ├── about.md      →  output/about.html      →  GET /about
│   └── docs/
│       └── guide.md  →  output/docs/guide.html →  GET /docs/guide
│
└── content/          ← articles (queryable via ContentRepository)
    ├── my-post.md    →  output/my-post.html    →  GET /my-post
    └── 2025/
        └── news.md   →  output/2025/news.html  →  GET /2025/news

At startup, SiteGenerator.Generate() converts pages, and ContentRepository.Build() converts articles. Both write pre-generated HTML to the same output directory. The existing route transformer serves all of it with a single catch-all route.

.md files  ──►  FrontMatterParser  ──►  MarkdownConverter  ──►  .html files
                                                                       │
                                              MarkdownPageRouteTransformer
                                                                       │
                                                          ASP.NET Core routes

Requirements

• .NET 8, 9, or 10
• ASP.NET Core (Microsoft.AspNetCore.App framework reference)

Installation

dotnet add package Anudwigna.StaticMarkdownEngine --prerelease

Or in your .csproj:

<PackageReference Include="Anudwigna.StaticMarkdownEngine" Version="1.0.0-beta.2" />

Quick Start

1. Register services in Program.cs

using Anudwigna.StaticMarkdownEngine.AspNetCore;
using Anudwigna.StaticMarkdownEngine.Content;
using Anudwigna.StaticMarkdownEngine.Core;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

// Pages engine
builder.Services.AddMarkdownEngine(options =>
{
    options.OutputDirectory = Path.Combine(builder.Environment.ContentRootPath, "output");
});

// Content query API (optional — only needed if you use the content/ folder)
builder.Services.AddContentRepository(options =>
{
    options.ContentDirectory = Path.Combine(builder.Environment.ContentRootPath, "content");
    options.OutputDirectory  = Path.Combine(builder.Environment.ContentRootPath, "output");
});

var app = builder.Build();

2. Generate HTML at startup

// Pages: input/ → output/
var generator = app.Services.GetRequiredService<SiteGenerator>();
generator.Generate(
    inputDir:  Path.Combine(app.Environment.ContentRootPath, "input"),
    outputDir: Path.Combine(app.Environment.ContentRootPath, "output"));

// Articles: content/ → output/ + in-memory index
var contentRepo = app.Services.GetRequiredService<ContentRepository>();
contentRepo.Build();

app.UseRouting();
app.MapMarkdownPages();
app.Run();

3. Register the Tag Helper

In Views/_ViewImports.cshtml:

@addTagHelper *, Anudwigna.StaticMarkdownEngine

4. Create a Razor view for Markdown pages

In Views/MarkdownPage/Render.cshtml:

@{
    Layout = "_Layout";
    ViewData["Title"] = ViewBag.Title;
}

<article class="markdown-body">
    <markdown-content html-content="@ViewBag.HtmlContent" />
</article>

5. Write Markdown content

input/about.md — a static page:

---
title: "About"
description: "Learn more about this site"
---

# About

Welcome! Check out our [home page](index.md).

content/my-first-post.md — a queryable article:

---
title: "My First Post"
description: "Hello from the content folder"
date: 2025-06-01
tags: intro
---

# My First Post

This article is queryable via `ContentRepository.Query()`.

Content API

The ContentRepository service provides a LINQ-based query API over all articles in your content/ folder. Routes for articles are derived directly from the file path with no prefix — content/my-post.md → /my-post.

Querying articles

// Inject ContentRepository into a controller or Razor Page
public class IndexModel : PageModel
{
    private readonly ContentRepository _content;

    public IReadOnlyList<ContentItem> TopPosts { get; private set; } = [];

    public IndexModel(ContentRepository content) => _content = content;

    public void OnGet()
    {
        // Top 5 articles by date, newest first
        TopPosts = _content.Query()
            .OrderByDescending(p => p.FrontMatter.Date ?? DateTime.MinValue)
            .Take(5)
            .ToList();
    }
}

Because Query() returns a plain IEnumerable<ContentItem>, any LINQ operator works:

// Filter by a custom front matter field
var tagged = _content.Query()
    .Where(p => p.FrontMatter.Extra.TryGetValue("tags", out var t)
             && t?.ToString()?.Contains("dotnet") == true)
    .ToList();

// Look up a single article by its URL
var post = _content.GetByRoute("/my-first-post");

Rendering links in a Razor view

@foreach (var post in Model.TopPosts)
{
    <article>
        <h2><a href="@post.Route">@post.FrontMatter.Title</a></h2>
        <time>@post.FrontMatter.Date?.ToString("MMM d, yyyy")</time>
        <p>@post.Excerpt</p>
        <a href="@post.Route">Read more →</a>
    </article>
}

ContentItem properties

Configuration Reference

AddMarkdownEngine

builder.Services.AddMarkdownEngine(options =>
{
    options.OutputDirectory = Path.Combine(builder.Environment.ContentRootPath, "output");
});

AddContentRepository

builder.Services.AddContentRepository(options =>
{
    options.ContentDirectory = Path.Combine(builder.Environment.ContentRootPath, "content");
    options.OutputDirectory  = Path.Combine(builder.Environment.ContentRootPath, "output");
    options.ExcerptLength    = 200; // optional, default is 200
});

YAML Front Matter Reference

Front matter is a YAML block delimited by --- at the top of a Markdown file.

---
title: "Page Title"
description: "A short description shown in meta tags or previews"
layout: "_Layout"
date: 2025-06-15
tags: dotnet, aspnetcore
author: "Ada Lovelace"
---

# Page content starts here

Accessing custom fields:

var author = item.FrontMatter.Extra["author"]?.ToString();

Tag Helper Reference

The <markdown-content> tag helper renders HTML content inside a Razor view. It produces no wrapper element — it outputs only the HTML.

From an inline HTML string (recommended)

<markdown-content html-content="@ViewBag.HtmlContent" />

From a file path

<markdown-content html-file="/absolute/path/to/output/about.html" />

CLI Reference

CliRunner provides a generate command for use in apps that expose a CLI entry point.

Wiring up in Program.cs

using Anudwigna.StaticMarkdownEngine.Cli;

if (args.Length > 0)
    return await CliRunner.RunAsync(args);

// Otherwise start the web app as normal

generate command

dotnet run -- generate [--input <path>] [--output <path>]

Example:

dotnet run -- generate -i content -o wwwroot/pages

Output:

Generating site from 'C:\myapp\content' → 'C:\myapp\wwwroot\pages'...
  ✓  /          →  wwwroot/pages/index.html
  ✓  /about     →  wwwroot/pages/about.html

Done! Generated 2 page(s).

API Reference

SiteGenerator

Recursively converts all .md files in a source directory to .html files.

var generator = new SiteGenerator(); // or inject via DI

IReadOnlyList<MarkdownPage> pages = generator.Generate(
    inputDir:  "/path/to/input",
    outputDir: "/path/to/output");

ContentRepository

Scans the content/ directory, generates HTML, and provides a LINQ-queryable in-memory index.

// Call once at startup
contentRepo.Build();

// LINQ query
var recent = contentRepo.Query()
    .OrderByDescending(p => p.FrontMatter.Date)
    .Take(5)
    .ToList();

// Direct lookup
ContentItem? post = contentRepo.GetByRoute("/my-post");

MarkdownConverter

Converts a single Markdown string to a MarkdownPage.

var converter = new MarkdownConverter(); // or inject via DI

MarkdownPage page = converter.Convert(rawMarkdown);
Console.WriteLine(page.FrontMatter.Title);
Console.WriteLine(page.HtmlContent);

MarkdownPage

FrontMatterParser

var parser = new FrontMatterParser();
var (frontMatter, body) = parser.Parse(rawMarkdown);

Project Structure

static_markdown_engine/
├── src/
│   └── Anudwigna.StaticMarkdownEngine/      # NuGet package
│       ├── AspNetCore/
│       │   ├── MarkdownEngineExtensions.cs  # AddMarkdownEngine / AddContentRepository / MapMarkdownPages
│       │   ├── MarkdownPageRouteTransformer.cs
│       │   ├── MarkdownPageRouteOptions.cs
│       │   └── MarkdownContentTagHelper.cs  # <markdown-content> tag helper
│       ├── Cli/
│       │   └── CliRunner.cs                 # System.CommandLine entry point
│       ├── Content/
│       │   ├── ContentRepository.cs         # Query API + HTML generation for articles
│       │   └── ContentRepositoryOptions.cs
│       ├── Core/
│       │   ├── FrontMatterParser.cs         # YAML extraction
│       │   ├── LinkRewriter.cs              # .md → route link rewriting
│       │   ├── MarkdownConverter.cs         # Markdig rendering pipeline
│       │   └── SiteGenerator.cs            # Folder sync: input/ → output/
│       └── Models/
│           ├── ContentItem.cs               # Article model for the query API
│           ├── FrontMatter.cs
│           └── MarkdownPage.cs
├── tests/
│   └── Anudwigna.StaticMarkdownEngine.Tests/ # xUnit + FluentAssertions (42 tests)
└── samples/
    └── Anudwigna.SampleWeb/                  # ASP.NET Core demo application
        ├── content/                          # Sample articles (queryable)
        └── input/                            # Sample static pages

Dependencies

License

This project is licensed under the MIT License.