Viae.Fluid.Markdown 0.1.5

Viae.Fluid.Markdown

A .NET library that provides Markdown rendering support for Fluid template engine, with special support for ASP.NET MVC applications.

Features

• 🚀 Easy Integration - Simple setup with Fluid templates
• 📝 GitHub Flavored Markdown - Full support via Markdig's advanced extensions
• 🎨 MVC Support - Special adapter for ASP.NET MVC to prevent double-encoding
• ⚙️ Customizable - Configure Markdig pipeline extensions as needed
• 🧪 Well Tested - Comprehensive test coverage with 60+ unit tests
• 📖 Fully Documented - Complete XML documentation for IntelliSense

Supported Markdown Features

With the default configuration, this library supports:

• Basic Markdown: Bold, italic, headings, links, images, code blocks
• Tables: Pipe tables and grid tables
• Task Lists: - [ ] and - [x] checkboxes
• Strikethrough: ~~text~~
• Auto-identifiers: Automatic heading IDs
• Footnotes: [^1] style footnotes
• Definition Lists: Term and definition syntax
• Abbreviations: Automatic abbreviation expansion
• And more via Markdig's advanced extensions

Installation

dotnet add package Viae.Fluid.Markdown

Quick Start

Basic Usage (Non-MVC)

using Viae.Fluid.Markdown;

// Create the filter and template options
var (filter, options) = FluidMarkdownCoreRegistration.CreateCore();

// Create a Fluid template context
var context = new TemplateContext(options);
context.SetValue("content", "**Hello** from _Markdown_!");

// Parse and render the template
var parser = new FluidParser();
if (parser.TryParse("{{ content | markdown }}", out var template, out var error))
{
    var output = await template.RenderAsync(context);
    Console.WriteLine(output);
    // Output: <p><strong>Hello</strong> from <em>Markdown</em>!</p>
}

ASP.NET MVC Usage

For MVC applications, use the MarkdownMvcAdapter to prevent HTML double-encoding:

using Viae.Fluid.Markdown;

// In your Startup.cs or Program.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton(sp =>
    {
        var (coreFilter, _) = FluidMarkdownCoreRegistration.CreateCore();
        var mvcAdapter = new MarkdownMvcAdapter(coreFilter);
        var options = new TemplateOptions();
        mvcAdapter.Register(options);
        return options;
    });
}

Then in your Razor views with Fluid:

@* The markdown filter will render HTML without double-encoding *@
@await RenderAsync("{{ post.content | markdown }}")

Custom Configuration

Customize the Markdig pipeline to enable specific extensions:

using Viae.Fluid.Markdown;
using Markdig;

var customOptions = new MarkdownFilterOptions
{
    ConfigurePipeline = builder => builder
        .UseAdvancedExtensions()      // GitHub Flavored Markdown
        .UseEmphasisExtras()           // Extra emphasis features
        .UseGridTables()               // Grid-style tables
        .UsePipeTables()               // Pipe-style tables
        .UseTaskLists()                // Task list checkboxes
        .UseAutoIdentifiers()          // Auto heading IDs
};

var (filter, templateOptions) = FluidMarkdownCoreRegistration.CreateCore(customOptions);

API Overview

Core Classes

IMarkdownRenderer

Interface for Markdown rendering implementations.

public interface IMarkdownRenderer
{
    string ToHtml(string markdown);
}

MarkdigMarkdownRenderer

Markdig-based implementation of IMarkdownRenderer.

var pipeline = new MarkdownPipelineBuilder().UseAdvancedExtensions().Build();
var renderer = new MarkdigMarkdownRenderer(pipeline);
var html = renderer.ToHtml("**bold text**");

MarkdownFilter

Fluid filter for Markdown rendering (returns plain strings).

var filter = new MarkdownFilter(renderer);
var options = new TemplateOptions();
filter.Register(options);
// Registers filters: "markdown" and "markdownify"

MarkdownMvcAdapter

MVC-specific adapter that wraps output in HtmlString.

var adapter = new MarkdownMvcAdapter(coreFilter);
var options = new TemplateOptions();
adapter.Register(options);
// Use in MVC views to prevent double-encoding

MarkdownFilterOptions

Configuration options for the Markdown pipeline.

var options = new MarkdownFilterOptions
{
    ConfigurePipeline = builder => builder.UseAdvancedExtensions()
};

FluidMarkdownCoreRegistration

Factory class for easy setup.

var (filter, options) = FluidMarkdownCoreRegistration.CreateCore();

Filter Names

Both filters are registered under two names for compatibility:

• markdown - Standard filter name
• markdownify - Jekyll/Liquid compatible alias

Both can be used interchangeably:

{{ content | markdown }}
{{ content | markdownify }}

Architecture

When to Use What

Class Hierarchy

IMarkdownRenderer (interface)
└── MarkdigMarkdownRenderer (Markdig implementation)
    └── MarkdownFilter (Fluid filter, returns string)
        └── MarkdownMvcAdapter (MVC adapter, returns HtmlString)

Examples

Example 1: Blog Post Rendering

var (filter, options) = FluidMarkdownCoreRegistration.CreateCore();
var context = new TemplateContext(options);

var blogPost = @"
# My Blog Post

This is a **markdown** blog post with:

- Bullet points
- *Italic text*
- [Links](https://example.com)

## Code Example

```csharp
Console.WriteLine(""Hello World"");

";

context.SetValue("post", blogPost); var template = FluidTemplate.Parse("{{ post | markdown }}"); var html = await template.RenderAsync(context);

### Example 2: Multiple Markdown Fields

```csharp
var context = new TemplateContext(options);
context.SetValue("title", "# Welcome");
context.SetValue("excerpt", "This is a **short** excerpt.");
context.SetValue("content", "Full article content here...");

var template = FluidTemplate.Parse(@"
<article>
    <header>{{ title | markdown }}</header>
    <aside>{{ excerpt | markdown }}</aside>
    <main>{{ content | markdown }}</main>
</article>
");

var html = await template.RenderAsync(context);

Example 3: Custom Pipeline (Minimal Extensions)

// Create a minimal Markdown renderer with only basic features
var minimalOptions = new MarkdownFilterOptions
{
    ConfigurePipeline = builder => builder
        .UseEmphasisExtras()  // Bold and italic only
        .UsePipeTables()      // Tables only
};

var (filter, options) = FluidMarkdownCoreRegistration.CreateCore(minimalOptions);

Testing

The library includes comprehensive tests (60+ test cases) using MSTest and FluentAssertions:

cd tests/Viae.Fluid.Markdown.Tests
dotnet test

Test coverage includes:

• All Markdown features (bold, italic, links, tables, etc.)
• Null and empty string handling
• Custom pipeline configurations
• Filter registration
• MVC adapter HtmlString wrapping

Dependencies

• Fluid.Core (^2.30.0) - Liquid template engine
• Markdig (^0.43.0) - Markdown processor
• Microsoft.AspNetCore.Html.Abstractions (^2.3.0) - For MVC support

Target Framework

• .NET Standard 2.0 (compatible with .NET Core 2.0+, .NET Framework 4.6.1+, .NET 5+)

Contributing

This library is part of the Viae project. Contributions are welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Built with Fluid by Sébastien Ros
• Markdown processing by Markdig by Alexandre Mutel

Related Projects

• Fluid - .NET Liquid template engine
• Markdig - Fast, powerful Markdown processor
• Viae - Parent project

Support

For questions, issues, or feature requests:

• Create an issue in the Viae repository
• Refer to the XML documentation in your IDE
• Check the Fluid documentation
• Check the Markdig documentation