Codli.CMarkdown.Blazor 0.4.0

Codli.CMarkdown.Blazor

Codli.CMarkdown.Blazor is a Razor Class Library for rendering and editing Markdown in Blazor applications. It ships with a bundled JavaScript core, a YAML-to-CSS theme compiler, safe HTML output, and reusable viewer/editor components.

Features

• ICMarkdownRenderService for Markdown → HTML/CSS rendering
• CMarkdownView and CMarkdownStyledView components
• CMarkdownEditor with Wysiwyg and RawWithPreview modes
• bundled static web assets, loaded from _content/Codli.CMarkdown.Blazor/
• optional image source remapping and pasted image upload hook

Installation

dotnet add package Codli.CMarkdown.Blazor

Register the service in your Blazor app:

using CMarkdown.Blazor;

builder.Services.AddCMarkdown();

No separate npm package is required for the Blazor integration. The package serves its JavaScript assets automatically through static web assets.

Quick Start

Render Markdown through a component:

@using CMarkdown.Blazor.Components

<CMarkdownStyledView Markdown="@Markdown" ThemeYaml="@ThemeYaml" />

@code {
    private string Markdown = "# Hello CMarkdown";

    private string ThemeYaml =
        """
        id: docs
        version: 1.0.0
        tokens:
          font:
            body: "ui-sans-serif, system-ui, sans-serif"
            mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
            sizeBase: 16px
            lineHeight: 1.6
          color:
            bg: "#ffffff"
            text: "#0f172a"
            border: "#cbd5e1"
            accent: "#0f766e"
            codeBg: "#f8fafc"
            codeText: "#0f172a"
          radius:
            sm: 4px
            md: 8px
          space:
            4: 16px
        classes:
          md-root:
            color: "var(--md-color-text)"
            fontFamily: "var(--md-font-body)"
            fontSize: "var(--md-font-sizeBase)"
            lineHeight: "var(--md-font-lineHeight)"
          md-p:
            margin: "0 0 var(--md-space-4) 0"
          md-a:
            color: "var(--md-color-accent)"
            textDecoration: "underline"
        """;
}

Render through the service when you need direct access to HTML and CSS:

@inject ICMarkdownRenderService MarkdownRenderer

@if (!string.IsNullOrWhiteSpace(_css))
{
    <style>@_css</style>
}

@((MarkupString)_html)

@code {
    private string _html = string.Empty;
    private string _css = string.Empty;

    protected override async Task OnInitializedAsync()
    {
        var result = await MarkdownRenderer.RenderAsync("# Hello", ThemeYaml);
        _html = result.Html;
        _css = result.Css;
    }

    private const string ThemeYaml = """
    id: docs
    version: 1.0.0
    tokens:
      color:
        text: "#111827"
    classes:
      md-root:
        color: "var(--md-color-text)"
    """;
}

When using ICMarkdownRenderService directly in a Blazor Web App with server-side prerendering, call it only after the interactive circuit is available. The viewer components handle this internally, but direct JS interop during prerender is still too early.

Editor

The editor component supports two modes and standard Blazor binding:

@using CMarkdown.Blazor.Components

<CMarkdownEditor @bind-Value="_content"
                 ThemeYaml="@ThemeYaml"
                 InitialMode="EditorMode.RawWithPreview" />

@code {
    private string _content = "# Draft";
    private string ThemeYaml = "...";
}

Image paste workflow

CMarkdownEditor can call back into your app when the user pastes an image:

<CMarkdownEditor @bind-Value="_content"
                 ThemeYaml="@ThemeYaml"
                 ImageSources="@_imageSources"
                 OnImagePaste="UploadImageAsync" />

private readonly Dictionary<string, string> _imageSources = new(StringComparer.Ordinal);

private async Task<CMarkdownImagePasteResult?> UploadImageAsync(CMarkdownImagePasteFile file)
{
    var uploaded = await _files.UploadAsync(file);
    if (uploaded is null)
    {
        return null;
    }

    _imageSources[uploaded.MarkdownUrl] = uploaded.RenderUrl!;
    return uploaded;
}

Public API

• builder.Services.AddCMarkdown()
• builder.Services.AddCMarkdown(Action<CMarkdownOptions>)
• ICMarkdownRenderService
• CMarkdownRenderResult
• CMarkdownView
• CMarkdownStyledView
• CMarkdownEditor
• CMarkdownImagePasteFile
• CMarkdownImagePasteResult

Styling Contract

The renderer produces stable md-* classes. These classes are part of the public styling contract.

• Root: md-root
• Blocks: md-p, md-h1..md-h6, md-ul, md-ol, md-li, md-blockquote, md-hr, md-pre, md-codeblock, md-table, md-th, md-td
• Inline: md-a, md-code, md-strong, md-em
• Media: md-img

Production Examples

This library is used in Codli applications in two main ways:

• Rise: request documentation editing and preview flows with CMarkdownEditor, custom YAML themes, and pasted-image handling
• Rift: manual pages rendered through ICMarkdownRenderService into application-specific shells

Notes

• one JS interop call returns both HTML and CSS
• ICMarkdownRenderService caches rendered output by Markdown, theme, and image source mapping
• the default module path is ./_content/Codli.CMarkdown.Blazor/cmarkdown.blazor.js
• raw HTML is blocked by the core renderer; link handling is sanitized in the JavaScript core