OfficeIMO.Markdown 3.6.1

Prefix Reserved
dotnet add package OfficeIMO.Markdown --version 3.6.1
                    
NuGet\Install-Package OfficeIMO.Markdown -Version 3.6.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OfficeIMO.Markdown" Version="3.6.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OfficeIMO.Markdown" Version="3.6.1" />
                    
Directory.Packages.props
<PackageReference Include="OfficeIMO.Markdown" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OfficeIMO.Markdown --version 3.6.1
                    
#r "nuget: OfficeIMO.Markdown, 3.6.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OfficeIMO.Markdown@3.6.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OfficeIMO.Markdown&version=3.6.1
                    
Install as a Cake Addin
#tool nuget:?package=OfficeIMO.Markdown&version=3.6.1
                    
Install as a Cake Tool

OfficeIMO.Markdown - Markdown builder, reader, and HTML renderer

nuget version nuget downloads

OfficeIMO.Markdown is the core Markdown package in the OfficeIMO family. It builds Markdown, parses Markdown into a typed document model, projects native AST snapshots for hosts, and renders HTML without external runtime dependencies.

If OfficeIMO saves you time, please consider supporting the work through GitHub Sponsors or PayPal.

Install

dotnet add package OfficeIMO.Markdown

Quick start

using OfficeIMO.Markdown;

var document = MarkdownDocument.Create()
    .FrontMatter(new { title = "OfficeIMO.Markdown", tags = new[] { "docs", "reporting" } })
    .H1("OfficeIMO.Markdown")
    .P("Typed Markdown builder, reader, and HTML renderer for .NET.")
    .Ul(list => list
        .Item("Build Markdown with a fluent API")
        .Item("Parse Markdown into typed blocks and inlines")
        .Item("Render HTML fragments or full documents"))
    .Code("powershell", "dotnet add package OfficeIMO.Markdown");

string markdown = document.ToMarkdown();
string htmlFragment = document.ToHtml(new MarkdownHtmlExportOptions { Kind = MarkdownHtmlKind.Fragment });
string htmlDocument = document.ToHtml(new MarkdownHtmlExportOptions { Kind = MarkdownHtmlKind.Document });

The chaining methods are shortcuts for the model methods, which return the block they append: H1–H6 call AddHeading(text, level), P calls AddParagraph, Ul, Ol and Dl call AddList, AddOrderedList and AddDefinitionList, Image calls AddImage, and Table and TableAuto call AddTable. Add returns the same concrete block you append. AddRange returns a read-only snapshot of its inputs in source order; input enumeration and null validation finish before the document changes.

using OfficeIMO.Markdown;

using var document = MarkdownDocument.Create();
HeadingBlock heading = document.AddHeading("Deployment", 2);
ParagraphBlock paragraph = document.AddParagraph("Deployment ");
paragraph.Inlines.Text("complete");
OrderedListBlock steps = document.AddOrderedList(new[] { "Build", "Verify" });
steps.Start = 3;
var added = document.AddRange(new IMarkdownBlock[] {
    new HeadingBlock(2, "Next steps"),
    new ParagraphBlock(new InlineSequence().Text("Verify the service."))
});
Console.WriteLine(document.ToMarkdown());

DefinitionListBlock.AddEntry returns the entry bound to the list. Editing its Term or DefinitionBlocks changes the rendered output. AddGroup returns the stored group, and MarkdownTable.AddRow returns the stored, editable cell array.

Image display sizes

Image display dimensions use OfficeLength. Unitless Markdown hints such as {width=96 height=48} and HTML image dimensions mean CSS pixels at 96 DPI. The same image occupies 72 by 36 points in Word and PDF. Intrinsic raster pixels and relative layout percentages are separate from these display lengths.

using OfficeIMO;
using OfficeIMO.Markdown;

using var document = MarkdownDocument.Create();
document.Image("images/badge.png", "Badge",
    width: OfficeLength.Inches(1), height: OfficeLength.Pixels(48));
string markdown = document.ToMarkdown(); // ![Badge](images/badge.png){width=96 height=48}
string html = document.ToHtml();          // width="96" height="48"

ImageBlock.Width, ImageBlock.Height and the corresponding native image properties expose nullable physical lengths. Rich Markdown emits invariant pixel numbers; HTML emits whole-pixel attributes and preserves fractional pixel dimensions in CSS. HTML import accepts absolute CSS length units; percentages stay outside physical image hints.

Typed tables

AddTable returns the added TableBlock, which remains editable. The shared OfficeTableOptions controls column selection, order, headers, formatting and alignment. MarkdownTableOptions also enables numeric and date alignment; explicit column alignments take precedence.

using OfficeIMO;
using OfficeIMO.Markdown;

using var document = MarkdownDocument.Create();
var rows = new[] {
    new { Product = "Paper", Quantity = 12 },
    new { Product = "Envelopes", Quantity = 24 }
};
var options = new MarkdownTableOptions();
options.HeaderRenames["Quantity"] = "In stock";
var table = document.AddTable(rows, options);
table.Rows.Add(new[] { "Labels", "48" });
Console.WriteLine(document.ToMarkdown());

Typed rows use declared public properties and fields, or the first dictionary row's string keys. The source is enumerated once. Projection rejects more than 10,000 data rows or 100 selected columns before adding the block. Formatter failures propagate. Explicit selector overloads support trim-safe column selection without reflection. Runtime data can be passed as object to retain scalar, property/value and dictionary-union projection.

What it does

  • Builds Markdown documents with headings, paragraphs, lists, task lists, tables, code blocks, callouts, details, front matter, footnotes, table-of-contents helpers, and semantic fenced blocks.
  • Parses Markdown into a typed MarkdownDocument object model with headings, blocks, inlines, anchors, source spans, front matter, and transform diagnostics.
  • Renders HTML fragments or full HTML documents with configurable profiles, CSS delivery, Prism options, Mermaid/chart/math shell assets, and safe defaults.
  • Provides native AST projection for editor, transcript, chat, and document hosts that need stable block ids and DTO-style snapshots.
  • Supports AOT-sensitive code paths through typed selectors and explicit overloads while leaving reflection helpers available for convenience scenarios.

Common tasks

Literal text without HTML entities

Use document.ToMarkdown(new MarkdownSaveOptions { TextEscapingMode = MarkdownTextEscapingMode.LiteralBackslash }) to write literal model text with Markdown backslash escapes. Ordinary parentheses and ampersands remain literal; HTML-like text and entity starts are escaped. Unstructured table strings are treated as literal text, while parsed and structured table nodes retain explicit Markdown formatting. The default writer mode keeps its existing behavior.

Tables from typed objects

var results = new[] {
    new { Name = "Alice", Role = "Dev", Score = 98.5 },
    new { Name = "Bob", Role = "Ops", Score = 91.0 }
};

var document = MarkdownDocument.Create()
    .H2("Team")
    .Table(table => table.FromSequence(results,
        ("Name", item => item.Name),
        ("Role", item => item.Role),
        ("Score", item => item.Score)));

Load or parse directly, with diagnostics when needed

MarkdownDocument document = MarkdownDocument.Load("README.md");
using MarkdownDocument inspected = MarkdownDocument.Load("README.md", null, out OfficeConversionReport report);

foreach (var heading in document.GetHeadingInfos()) {
    Console.WriteLine($"{heading.Level}: {heading.Text} -> {heading.Anchor}");
}

MarkdownDocument.Parse(...) and Load(...) return the native document. Use the overload with out OfficeConversionReport report when syntax-tree and transform diagnostics must travel with it. Async loading returns the document and accepts a final cancellation token.

Markdown writing also accepts cancellation: document.ToMarkdown(writeOptions, cancellationToken) and document.ToBytes(writeOptions, cancellationToken) check it during serialization. SaveAsync passes its token through serialization before writing the destination. Custom renderers can use context.CancellationToken for their own work.

Native AST snapshot

MarkdownNativeDocument native = MarkdownNativeDocument.Parse("""
# Investigation

See **CPU** in [dashboard](https://example.com).
""");

var snapshot = native.ToSnapshot();

Front matter, task lists, callouts, details, and TOC

var document = MarkdownDocument.Create()
    .FrontMatter(new {
        title = "Deployment checklist",
        owner = "Platform",
        tags = new[] { "runbook", "deployment" }
    })
    .H1("Deployment checklist")
    .Toc(options => {
        options.Title = "Contents";
        options.MinLevel = 2;
        options.MaxLevel = 3;
    })
    .H2("Pre-flight")
    .Ul(list => list
        .ItemTask("Packages published", done: true)
        .ItemTask("Change approved")
        .ItemTask("Rollback plan attached"))
    .Callout("warning", "Freeze window", "Do not deploy outside the approved window.")
    .Details("Rollback commands", body => body
        .Code("powershell", "dotnet nuget locals all --clear"));

string markdown = document.ToMarkdown();

HTML fragments, full documents, and parts

var document = MarkdownDocument.Create()
    .H1("Status")
    .P(p => p.Text("Generated ").Bold("today").Text(" for the portal."))
    .TableAuto(table => table
        .Headers("Service", "Status", "Latency")
        .Row("API", "Green", "42")
        .Row("Jobs", "Yellow", "210"));

string fragment = document.ToHtml(new MarkdownHtmlExportOptions { Kind = MarkdownHtmlKind.Fragment });
string fullPage = document.ToHtml(new MarkdownHtmlExportOptions { Kind = MarkdownHtmlKind.Document });
MarkdownHtmlParts parts = document.ToHtmlParts();

// Without options, SaveAsHtml writes a complete, unstyled page.
document.SaveAsHtml("status.html");

The default Plain style keeps the source markup and table alignment without a stylesheet. Select MarkdownHtmlStyle.Clean, Word, a GitHub style, or an explicit Theme to add presentation styling. Clean declares --office-* custom properties for colours, fonts, type scale and table tokens.

Parse, inspect, and rewrite a document

var parsed = MarkdownDocument.Parse(File.ReadAllText("README.md"),
    MarkdownLoadOptions.CreateOfficeIMOProfile());

if (!parsed.HasHeading("Install")) {
    parsed.H2("Install")
          .Code("powershell", "dotnet add package OfficeIMO.Markdown");
}

foreach (var heading in parsed.GetHeadingInfos()) {
    Console.WriteLine($"{heading.Level}: {heading.Text} -> #{heading.Anchor}");
}

File.WriteAllText("README.normalized.md", parsed.ToMarkdown());

Content provenance

MarkdownProvenance.Inspect(markdown) reports standards-defined structured C2PA blocks and unstructured C2PA text wrappers. MarkdownProvenance.Remove(markdown) removes selected, structurally valid carriers while preserving surrounding Markdown text. File overloads use bounded reads and atomic writes. Optional cryptographic C2PA verification remains in OfficeIMO.Security.

Adjacent packages

Package Use it for
OfficeIMO.Markdown.Html HTML to Markdown document conversion.
OfficeIMO.Markdown.Pdf Markdown to PDF through OfficeIMO.Pdf.
OfficeIMO.MarkdownRenderer WebView/browser-friendly shell rendering and incremental updates.
OfficeIMO.Word.Markdown Word to/from Markdown conversion.
OfficeIMO.Markup Markdown-inspired semantic authoring for OfficeIMO document outputs.
  • OfficeIMO.Markdown provides the Markdown model, parser, writer, and HTML renderer.
  • Use OfficeIMO.Markdown.Pdf for PDF output.
  • Use OfficeIMO.Markdown.Html for HTML ingestion.
  • Use OfficeIMO.MarkdownRenderer and its host-specific plug-ins for application shells.

Deeper docs

Targets and license

Dependency footprint

  • External: None; parsing, syntax, semantic models, and writing are first-party.
  • OfficeIMO: OfficeIMO.Core. The AST, parser, builder, transformations, and HTML renderer are first-party.

See the complete OfficeIMO package map for related formats and conversion paths.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

Operation Supported Partial Preserved Rejected Unsupported Not applicable
Create 1 0 0 0 0 0
Read 1 0 0 0 0 0
Edit 1 0 0 0 0 0
Preserve 0 1 0 0 0 0
Inspect 1 0 0 0 0 0
Validate 1 0 0 0 0 0
Remove 1 0 0 0 0 0
Convert 1 0 0 0 0 0

The complete rows for OfficeIMO.Markdown are published in the generated operation contract.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (20)

Showing the top 5 NuGet packages that depend on OfficeIMO.Markdown:

Package Downloads
OfficeIMO.Markdown.Html

HTML converter for OfficeIMO.Markdown - Convert HTML fragments or documents into OfficeIMO.Markdown documents and Markdown text.

OfficeIMO.Markdown.Pdf

PDF converter for OfficeIMO.Markdown - Export Markdown documents to PDF using the first-party OfficeIMO.Pdf engine.

OfficeIMO.Word.Markdown

Markdown converter for OfficeIMO.Word - Convert Word documents to/from Markdown using OfficeIMO.Markdown

OfficeIMO.Reader

Unified, read-only document extraction facade for OfficeIMO (Word/Excel/PowerPoint/Markdown/PDF) intended for AI ingestion.

OfficeIMO.MarkdownRenderer

WebView-friendly Markdown rendering helpers (shell + incremental updates) built on OfficeIMO.Markdown.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on OfficeIMO.Markdown:

Repository Stars
EvotecIT/PSWriteOffice
Moved to OfficeIMO. Development, releases, issues and pull requests: https://github.com/EvotecIT/OfficeIMO
Version Downloads Last Updated
3.6.1 925 11/10/2026
3.6.0 1,481 11/6/2026
3.5.3 2,671 10/31/2026
3.5.2 11,046 10/24/2026
3.5.1 10,960 10/16/2026
3.4.5 14,941 10/10/2026
3.4.4 10,313 9/27/2026
3.4.3 13,787 9/12/2026
3.4.2 1,975 9/9/2026
3.4.1 1,369 9/7/2026
3.4.0 1,112 9/6/2026
3.3.0 1,878 9/2/2026
3.2.7 1,486 8/29/2026
3.2.6 6,035 8/22/2026
3.2.5 1,096 8/21/2026
3.2.4 2,592 8/19/2026
3.2.3 2,033 8/17/2026
3.2.2 24,214 8/13/2026
3.2.1 1,488 8/11/2026
3.2.0 9,630 8/7/2026
Loading failed

0.6.0: adds semantic fenced-block AST support, fenced block extension APIs, improved quoted/container fence handling, and HTML parts/asset workflows aligned for downstream HTML-to-Markdown and host integrations.