Home Docs

MarkdownViewer
MdViewer
MD

BitMarkdownViewer is a native, SEO friendly Blazor component that renders Markdown to HTML entirely in C#, with no JavaScript interop and no third-party packages.

Notes

To use this component, you need to install the Bit.BlazorUI.Extras nuget package, as described in the Optional steps of the Getting started page.

Parsing and rendering happen entirely in C# (no JavaScript interop), so the component renders real DOM and works the same while prerendering, on the server, and on the client.

Usage

Basic

Native Markdown in Blazor

Rendered entirely in C# with no JavaScript and no third-party packages.

  • Real DOM output
  • Safe by default
  • Zero interop
GitHub flavored

GitHub Flavored Markdown

Supports strikethrough and bare links like https://bitplatform.dev

Task list

  • Parse Markdown in pure C#
  • Render the real render tree
  • Use any JavaScript

Table

FeatureBasicGitHub
Headings✔✔
Tables✔
Strikethrough✔
Advanced
Flavor:
Advanced: GitHub Flavored Markdown plus :sparkles: emoji and automatic heading ids.

BitMarkdownViewer

A native Blazor Markdown viewer written in pure C# - no JavaScript, no innerHTML, and no external dependencies zero external dependencies.

Why it exists

Most Blazor Markdown components wrap a JavaScript library and marshal strings across the interop boundary. This one parses Markdown into an AST and renders it straight to the Blazor render tree, so the output is real DOM.

Feature highlights

  • Headings (ATX # and Setext)
  • Bold, italic, bold italic, and strikethrough
  • inline code and fenced code blocks
  • Links and images
  • Ordered and unordered lists, including nesting:
    1. First item
    2. Second item
      • nested bullet
      • another one
    3. Third item
  • GitHub-style task lists:
    • Parse blocks
    • Parse inlines
    • Conquer the world

Code

Inline: var viewer = new BitMarkdownViewer();

public static BitMarkdownViewerDocumentNode Parse(string? markdown)
{
    var document = new BitMarkdownViewerDocumentNode();
    if (string.IsNullOrEmpty(markdown))
        return document;
    return document;
}

Blockquotes

"Any sufficiently advanced technology is indistinguishable from magic."

  • Arthur C. Clarke

Tables

FeatureSupportedNotes
HeadingsYesLevels 1-6
TablesYesWith column alignment
Task listsYesGitHub flavoured
Raw HTMLNoEscaped for safety

Safety

Link and image URLs are sanitized, so javascript: URIs are stripped and raw HTML in the source is rendered as text rather than executed.

Plugins (try the Flavor switch above)

With the Advanced flavor you also get emoji and autolinks:

Switch to Basic to see the same source rendered as plain CommonMark.

Made with C# and the Blazor render tree.

Custom pipeline

Custom pipeline ✨

This viewer uses a pipeline composed with only the extensions we picked: pipe tables, strikethrough, task lists, emoji and auto identifiers.

  • Old approach replaced
  • Anything left to do?

API

BitMarkdownViewer parameters
Name
Type
Default value
Description
Markdown string? null The Markdown string value to render as html elements.
Pipeline BitMarkdownViewerPipeline? null The processing pipeline (flavor set). Defaults to the basic CommonMark core with no extensions. Use one of the ready-made pipelines on BitMarkdownViewerPipelines (Basic, GitHub, Advanced) or build a custom one with BitMarkdownViewerPipelineBuilder.
BitComponentBase parameters
Name
Type
Default value
Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
IsEnabled bool true Gets or sets a value indicating whether the component is enabled and can respond to user interaction.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.
BitComponentBase public members
Name
Type
Default value
Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.
BitMarkdownViewerPipeline properties
An immutable, reusable Markdown processing configuration produced by a BitMarkdownViewerPipelineBuilder. Pipelines are thread-safe and should be cached and shared. Ready-made pipelines are available on BitMarkdownViewerPipelines (Basic, GitHub, Advanced).
Name
Type
Default value
Description
Basic static BitMarkdownViewerPipeline A pipeline with only the basic CommonMark core (no flavors).
Parse BitMarkdownViewerDocumentNode Parse(string? markdown) Parses Markdown source into an AST, applying all AST processors.
CreateRenderer BitMarkdownViewerMarkdownRenderer CreateRenderer() Creates a renderer bound to this pipeline's node renderers.
BitMarkdownViewerDocumentNode properties
The root of a parsed Markdown document. Inherits from BitMarkdownViewerMarkdownNode.
Name
Type
Default value
Description
Children List<BitMarkdownViewerMarkdownNode> [] The top-level child nodes of the document.
ChildNodes IList<BitMarkdownViewerMarkdownNode> The node's single child collection (returns Children).
BitMarkdownViewerMarkdownNode properties
The abstract base type for every node produced by the parser. Nodes expose their mutable child collections so that AST processors (plugins) can traverse and rewrite the tree generically, even for node types they did not define.
Name
Type
Default value
Description
ChildNodes virtual IList<BitMarkdownViewerMarkdownNode>? null The node's single child collection, if it has exactly one. Container nodes override this; leaf nodes return null.
ChildLists virtual IEnumerable<IList<BitMarkdownViewerMarkdownNode>> All mutable child collections owned by this node. Defaults to the single ChildNodes collection; nodes with several (e.g. a table's cells) override this to expose each one.
BitMarkdownViewerMarkdownRenderer properties
Walks an AST and dispatches each node to a matching node renderer. Renderers are probed in reverse registration order, so the last renderer registered for a node type wins, allowing pipeline extensions to override the core renderers.
Name
Type
Default value
Description
WriteNodes void WriteNodes(RenderTreeBuilder builder, IEnumerable<BitMarkdownViewerMarkdownNode> nodes) Renders a sequence of nodes.
WriteNode void WriteNode(RenderTreeBuilder builder, BitMarkdownViewerMarkdownNode node) Renders a single node using the matching renderer (last registered wins).
BitVisibility enum
Name
Value
Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).
BitDir enum
Name
Value
Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

You can give us your feedback through our GitHub repo by filing a new Issue or starting a new Discussion.

Or you can review / edit this page on GitHub.

Or you can review / edit this component on GitHub.
  • On this page