Khalid Abuhakmeh explores how to integrate Markdown files with YAML frontmatter as strongly-typed objects in ASP.NET Core, guiding readers through implementation with practical code and Razor Page usage.

Overview

Khalid Abuhakmeh explores an effective technique for integrating Markdown files, complete with YAML frontmatter, as strongly-typed objects within ASP.NET Core content applications. This approach bridges the gap between flexible content authoring and robust, type-safe access in C# code, facilitating easier data handling and presentation in Razor Pages.

The Problem: Leveraging Markdown and YAML

Markdown is popular for its readability and simplicity, and often content metadata is stored in YAML frontmatter. However, in traditional ASP.NET Core development, pulling this structured data into a strongly-typed model isn’t straightforward. Khalid sets out to simplify this by parsing Markdown and related YAML metadata directly into C# classes.

Sample Markdown with YAML Frontmatter

---
name: "Khalid Abuhakmeh"
profession: "Software Developer"
hobbies: ["video games", "movies", "boxing"]
---

## Summary

I am writing a little about myself here...

C# Model Representation

To represent the YAML part in C#, a class like the following is defined:

public class Asset {
    public string Name { get; set; } = "";
    public string Profession { get; set; } = "";
    public string[] Hobbies { get; set; } = [];
}

The MarkdownObject Class

Khalid introduces a MarkdownObject<T> class that:

  • Takes the content string.
  • Parses the Markdown and YAML frontmatter using Markdig and YamlDotNet.
  • Provides strongly-typed access to frontmatter as a C# object.
  • Renders Markdown content to HTML for use in Razor Pages.

Key library dependencies:

  • Markdig: For Markdown parsing and YAML extension.
  • YamlDotNet: For YAML deserialization into C# models.

Implementation Highlights

public class MarkdownObject<T> {
    // Setup markdown pipeline with YAML frontmatter
    // Initialize YAML deserializer
    public MarkdownObject(string content) {
        // Parse content and extract YAML frontmatter
        // Deserialize into strong type
        // Render remaining markdown to HTML
    }
    public T? FrontMatter { get; private set; }
    public IHtmlContent Html { get; private set; }
}

Razor Page Integration

In his demo, Markdown files are stored in a Data directory, each accessible via a slug. The Razor Page pulls the appropriate file, instantiates the MarkdownObject class, and renders the content along with metadata in a structured manner.

Example Usage in a Razor Page

@page "/profile/{slug}"
@model SuperContent.Pages.Profile
// Output strong-typed properties and HTML
@Model.Asset.FrontMatter?.Name
@Model.Asset.FrontMatter?.Profession
<ul>
@foreach (var hobby in @Model.Asset.FrontMatter?.Hobbies ?? Array.Empty<string>()) {
    <li>@hobby</li>
}
</ul>
@Model.Asset.Html

The backing model loads and sanitizes the file slug, reads the Markdown file, and sets up the Asset property:

public IActionResult OnGet() {
    // Sanitize slug, load relevant Markdown file, instantiate MarkdownObject
}

Try It Yourself

The accompanying code is available on Khalid’s GitHub for experimentation and further use.

Conclusion

This technique provides an elegant solution for developers wishing to store content and metadata in Markdown/YAML while retaining type safety and integration benefits in ASP.NET Core. Khalid encourages readers to try out the sample and provide feedback.

This post appeared first on Khalid Abuhakmeh’s Blog. Read the entire article here