Mdazor 0.0.0-alpha.0.13

Mdazor

A Markdig extension that lets you embed Razor components directly in Markdown for server-side rendering.

What is this?

Ever wanted to write Markdown like this:

# My Documentation

Here's some regular markdown content.

<AlertCard type="warning">
This is a **real Razor component** with Markdown content inside!

- It supports lists
- And *formatting*
- And even nested components!

<Button variant="primary">Click me!</Button>
</AlertCard>

More regular markdown continues here...

And have it actually render real Razor components server-side? That's what this does.

Why does this exist?

Writing documentation with static Markdown is fine, but sometimes you want to:

• Generate content programmatically using server-side Razor components
• Embed actual rendered UI components in your docs

How it works

This is a custom Markdig extension that:

1. Parses component tags - Recognizes <ComponentName prop="value">content</ComponentName> syntax in your Markdown
2. Uses Blazor's HtmlRenderer - Actually renders real Razor components server-side into static HTML
3. Handles nested content - Markdown inside components gets processed recursively
4. Graceful fallback - Unknown components just render as regular HTML tags

The magic happens in the parsing phase - we intercept component-looking tags before they get processed as regular HTML, instantiate actual Razor components, and render them using Blazor's server-side rendering to produce static HTML output.

Example Components

Your components just need to be normal Razor components:

@{
    var alertClass = Type switch
    {
        "success" => "alert-success",
        "warning" => "alert-warning",
        "danger" => "alert-danger",
        "info" => "alert-info",
        _ => "alert-primary"
    };
}

<div class="alert @alertClass" role="alert">
    @ChildContent
</div>

@code {
    [Parameter] public string Type { get; set; } = "primary";
    [Parameter] public RenderFragment? ChildContent { get; set; }
}

The ChildContent parameter gets populated with the processed Markdown content from inside the component tags.

Features

Component Syntax

<Icon name="star" size="24" />


<Card title="Hello World">
This content becomes the component's ChildContent parameter.
</Card>


<AlertBox type="info">
## This is a heading inside a component

And here's a nested component:
<Button onclick="alert('hi')">Click me</Button>

- Lists work too
- **Bold text**
- Everything you'd expect
</AlertBox>

Fallback for unknown components

If a component isn't registered, it just renders as HTML:

<SomeUnknownWidget foo="bar">content</SomeUnknownWidget>

Becomes: <someunknownwidget foo="bar">content</someunknownwidget> with the error message as an HTML comment.

Setup

1. Register your components:

services.AddMdazor()
    .AddMdazorComponent<AlertCard>()
    .AddMdazorComponent<Button>()
    .AddMdazorComponent<Icon>();

2. Use it:

Create your own pipeline, ensuring to inject your service provider so we can find the components:

var pipeline = new MarkdownPipelineBuilder()
    .UseMdazor(serviceProvider)
    .Build();
var html = Markdown.ToHtml(markdownContent, pipeline);

For advanced scenarios, you can still use the renderer directly:

var document = Markdown.Parse(markdownContent, pipeline);
using var writer = new StringWriter();
var renderer = new BlazorRenderer(writer, componentRegistry, serviceProvider);
renderer.Render(document);
var html = writer.ToString();

Technical Notes

• Uses Blazor's HtmlRenderer for actual server-side component rendering into static HTML
• Component parameters are mapped using reflection with case-insensitive matching
• Nested Markdown content is processed recursively using the same pipeline
• Async rendering is fully supported
• @inject works inside components, so you can inject services as usual

Limitations

• It doesn't handle whitespace all that great. If you are using a markdown element that relies on precise whitespace such as a code element or blockquote, don't indent your tags e.g.

  Do this:

  <Card>
  ```csharp
  var i = 2 + 2;
  ```
  </Card>
  

  Not this:

  <Card>
      ```csharp
      var i = 2 + 2;
      ```
  </Card>
  

• Server-side rendering only (components render to static HTML)

• Components need to be registered ahead of time

• No support for complex parameter types (just strings, numbers, bools for now)

• Component names must start with a capital letter (follows HTML custom element rules)

Project Structure

• Mdazor/ - The main library with the Markdig extension
• Mdazor.Demo/ - A Blazor Server app showing it in action
• Mdazor.Tests/ - Unit and integration tests

Running the Demo

cd Mdazor.Demo
dotnet run

Then check out the demo pages to see components embedded in Markdown.

Contributing

This is a skunkworks project, so don't expect enterprise-level polish. But if you find bugs or have ideas, PRs welcome!

The main areas that could use work:

• Support for more complex parameter types
• Fixing the aforementioned whitespace problems
• Client-side Blazor support
• Better error handling and diagnostics
• Performance optimizations
• More comprehensive documentation

License

MIT - do whatever you want with it.