Zaiets.Markdown.Renderer 1.0.0

Zaiets.Markdown.Renderer

Fast Markdown to HTML renderer for .NET 10 — GFM support, syntax highlighting, and built-in sanitization.

Features

• CommonMark compliant — headings, paragraphs, blockquotes, lists, code blocks, horizontal rules, inline code, emphasis, strong, links, images
• GitHub Flavored Markdown (GFM) — tables, task lists, strikethrough, autolinks
• Syntax highlighting — CSS-class spans (highlight.js-compatible) for C#, JavaScript, TypeScript, Python, Go, Rust, Java, SQL, and more — zero JS dependencies at render time
• HTML sanitization — allowlist-based XSS scrubber; safe for user-supplied content
• Typographer — optional em-dash, en-dash, ellipsis, and copyright substitutions
• Zero dependencies — pure .NET 10, no third-party packages
• Thread-safe — a single MarkdownRenderer instance can be used concurrently

Installation

dotnet add package Zaiets.Markdown.Renderer

Quick Start

using Zaiets.Markdown.Renderer;

// Simplest usage — extension method on string
string html = "# Hello, **world**!".ToHtml();

// With a renderer instance (recommended for repeated use)
var renderer = new MarkdownRenderer();
string html = renderer.Render("# Hello, **world**!");

// Full HTML document
string doc = renderer.RenderDocument(markdown, title: "My Page");

Options

var opts = new MarkdownOptions
{
    EnableGfm              = true,   // GitHub Flavored Markdown extensions
    EnableSyntaxHighlighting = true, // syntax-highlighted code blocks
    SanitizeOutput         = true,   // strip XSS vectors (recommended for user content)
    AutoLinks              = true,   // bare URLs → <a> tags
    ExternalLinkPolicy     = true,   // rel="nofollow noopener noreferrer" + target="_blank"
    GenerateHeadingIds     = true,   // <h2 id="slug"> for in-page anchor links
    SoftBreaks             = false,  // single newline → <br> (off by default)
    Typographer            = false,  // -- → &ndash;, --- → &mdash;, ... → &hellip;
    CodeBlockCssClass      = "code-block",
    HighlightCssPrefix     = "hljs",
    TableCssClass          = "table", // optional CSS class on <table>
    MaxNestingDepth        = 10,
};

var renderer = new MarkdownRenderer(opts);

Built-in presets

Fluent builder extensions

string html = markdown.ToHtml(
    MarkdownOptions.Default
        .WithTableClass("table table-striped")
        .WithTypographer()
        .WithSoftBreaks()
);

Available extension methods on MarkdownOptions:

Async / Stream API

// From a TextReader
using var reader = new StringReader(markdownText);
string html = await reader.RenderToHtmlAsync();

// From a Stream (UTF-8)
await using var file = File.OpenRead("docs/README.md");
string html = await file.RenderToHtmlAsync(MarkdownOptions.Trusted);

// Write directly to a TextWriter
await using var output = new StringWriter();
await stream.RenderToAsync(output);

Syntax Highlighting

No JavaScript is required at render time. The renderer emits <span class="hljs-keyword"> etc. Link any highlight.js-compatible theme CSS and the code blocks will light up.

<link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">

Supported languages (identifier in the fenced block):

csharp / cs, javascript / js, typescript / ts, python / py, go, rust, java, sql, bash / sh, yaml / yml

GFM Tables

| Name    | Type   | Required |
|---------|--------|:--------:|
| `id`    | int    |    ✓     |
| `email` | string |    ✓     |
| `bio`   | string |          |

Renders to a properly-aligned <table> with <thead> / <tbody>.

Task Lists

- [x] Write unit tests
- [x] Add README
- [ ] Publish to NuGet

Renders to <li class="task-list-item"><input type="checkbox" disabled ...>.

HTML Sanitization

When SanitizeOutput = true (default), the sanitizer:

• Strips <script>, <style>, <iframe>, <object>, <embed>, <form>, and similar tags entirely
• Removes event-handler attributes (onclick, onerror, etc.)
• Blocks dangerous URL schemes (javascript:, data:, vbscript:) in href/src
• Allows a curated set of safe HTML elements and attributes

You can also use the sanitizer independently:

using Zaiets.Markdown.Renderer;

string safeHtml = HtmlSanitizer.Sanitize(untrustedHtml);

API Reference

MarkdownRenderer

HtmlSanitizer

SyntaxHighlighter

License

MIT — Copyright © 2025 Vladyslav Zaiets