OfficeIMO.Markdown 0.6.0

OfficeIMO.Markdown — .NET Markdown Builder, Reader, and HTML Renderer

OfficeIMO.Markdown is a cross-platform .NET library for composing Markdown, parsing it back into a typed document model, and rendering it to HTML without external runtime dependencies.

• Targets: netstandard2.0, net472, net8.0, net10.0
• License: MIT
• NuGet: OfficeIMO.Markdown
• Dependencies: none

AOT / Trimming Notes

• The core builder, reader, and renderer APIs avoid external runtime dependencies and are straightforward to trim.
• Reflection-based helpers remain available for convenience scenarios such as FromAny(...).
• For NativeAOT or trimming-sensitive workloads, prefer typed overloads and explicit selectors.

using OfficeIMO.Markdown;

var people = new[] {
    new Person("Alice", "Dev", 98.5),
    new Person("Bob", "Ops", 91.0)
};

var doc = MarkdownDoc.Create()
    .Table(t => t.FromSequenceAuto(people));

doc.FrontMatter(FrontMatterBlock.FromObject(new BuildInfo { Version = "1.0.0" }));

public sealed record Person(string Name, string Role, double Score);
public sealed class BuildInfo {
    public string Version { get; set; } = "";
}

Install

dotnet add package OfficeIMO.Markdown

Hello, Markdown

using OfficeIMO.Markdown;

var doc = MarkdownDoc
    .Create()
    .FrontMatter(new { title = "OfficeIMO.Markdown", tags = new[] { "docs", "reporting" } })
    .H1("OfficeIMO.Markdown")
    .P("Typed Markdown builder, reader, and HTML renderer for .NET.")
    .H2("Quick start")
    .Ul(ul => ul
        .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");

var markdown = doc.ToMarkdown();
var htmlFragment = doc.ToHtmlFragment();
var htmlDocument = doc.ToHtmlDocument();

Common Tasks by Example

Builder: headings, callouts, lists, and code

var doc = MarkdownDoc.Create()
    .H1("Release Notes")
    .Callout("info", "Heads up", "This API is still evolving before 1.0.")
    .P("OfficeIMO.Markdown is suitable for document, reporting, and chat-style rendering flows.")
    .H2("Features")
    .Ul(ul => ul
        .Item("Typed AST/query model")
        .Item("TOC helpers")
        .Item("Front matter")
        .Item("HTML rendering"))
    .Code("csharp", "Console.WriteLine(\"Hello Markdown\");");

Tables from typed objects or explicit selectors

var results = new[] {
    new { Name = "Alice", Role = "Dev", Score = 98.5, Joined = "2024-01-10" },
    new { Name = "Bob", Role = "Ops", Score = 91.0, Joined = "2023-08-22" }
};

var doc = MarkdownDoc.Create()
    .H2("Team")
    .Table(t => t.FromSequence(results,
            ("Name", x => x.Name),
            ("Role", x => x.Role),
            ("Score", x => x.Score),
            ("Joined", x => x.Joined))
        .AlignNumericRight()
        .AlignDatesCenter());

TOC helpers and scoped navigation

var doc = MarkdownDoc.Create()
    .H1("Guide")
    .H2("Install")
    .H2("Usage")
    .H3("Tables")
    .H3("Lists")
    .TocAtTop("Contents", min: 2, max: 3)
    .H2("Appendix")
    .H3("Extra")
    .TocForPreviousHeading("Appendix Contents", min: 3, max: 3);

Parse Markdown into a typed document model

var parsed = MarkdownReader.Parse(File.ReadAllText("README.md"));

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

foreach (var block in parsed.DescendantsAndSelf()) {
    Console.WriteLine(block.GetType().Name);
}

if (parsed.HasDocumentHeader && parsed.TryGetFrontMatterValue<string>("title", out var title)) {
    Console.WriteLine("Title: " + title);
}

Semantic fenced blocks and reader extensions

var options = new MarkdownReaderOptions();
options.FencedBlockExtensions.Add(new MarkdownFencedBlockExtension(
    "Vendor charts",
    new[] { "vendor-chart" },
    context => new SemanticFencedBlock(MarkdownSemanticKinds.Chart, context.Language, context.Content, context.Caption)));

var parsed = MarkdownReader.Parse("""
```vendor-chart
{"type":"bar"}

""", options);

Use semantic fenced blocks when a fenced language represents a host contract or visual/document semantic rather than ordinary code.

### Portable reader profile

```csharp
var portable = MarkdownReader.Parse(markdown, MarkdownReaderOptions.CreatePortableProfile());

Use the portable profile when portability-sensitive ingestion matters more than OfficeIMO-specific conveniences. It disables OfficeIMO-only callout/task-list parsing and turns off bare literal autolinks.

Input normalization for chat or model output

var parsed = MarkdownReader.Parse(markdown, new MarkdownReaderOptions {
    InputNormalization = MarkdownInputNormalizationPresets.CreateChatTranscript()
});

var strictChat = MarkdownReader.Parse(markdown, new MarkdownReaderOptions {
    InputNormalization = MarkdownInputNormalizationPresets.CreateChatStrict()
});

var docs = MarkdownReader.Parse(markdown, new MarkdownReaderOptions {
    InputNormalization = MarkdownInputNormalizationPresets.CreateDocsLoose()
});

HTML fragments and full documents

var fragment = doc.ToHtmlFragment(new HtmlOptions {
    Style = HtmlStyle.GithubAuto
});

var fullPage = doc.ToHtmlDocument(new HtmlOptions {
    Title = "Release Notes",
    Style = HtmlStyle.Clean,
    CssDelivery = CssDelivery.Inline
});

doc.SaveHtml("release-notes.html", new HtmlOptions {
    Style = HtmlStyle.Word,
    CssDelivery = CssDelivery.ExternalFile
});

HTML parts and asset manifests

var parts = doc.ToHtmlParts(new HtmlOptions {
    EmitMode = AssetEmitMode.ManifestOnly,
    Prism = new PrismOptions { Enabled = true, Languages = { "csharp" } }
});

var merged = HtmlAssetMerger.Build(new[] { parts.Assets });

Use ToHtmlParts(...) and HtmlAssetMerger.Build(...) when a host wants to own the final HTML shell or deduplicate CSS/JS assets across multiple fragments.

Feature Highlights

• Builder API: headings, paragraphs, links, images, tables, code fences, callouts, footnotes, front matter, TOC helpers
• Reader API: typed blocks/inlines, syntax-tree spans, traversal helpers, heading queries, list-item queries, front matter lookups
• Semantic extensions: fenced block extension seam plus first-class semantic fenced-block nodes
• HTML rendering: fragment or full document, multiple built-in themes, inline/external/link CSS delivery, CDN/offline asset handling
• Host integration: HTML parts/assets model for advanced embedding and shell assembly
• Table helpers: generate tables from objects or sequences, per-column alignment, renames, transforms, and formatters
• Chat/docs ingestion: named input-normalization presets for transcript, strict chat, and docs cleanup workflows
• Deterministic output: stable markdown and HTML generation for snapshotting, diffs, and downstream export flows

Detailed Feature Matrix

• Documents
  • ✅ Fluent builder and explicit block model
  • ✅ Typed traversal helpers (TopLevelBlocks, DescendantsAndSelf, DescendantsOfType<T>())
  • ✅ Heading, front matter, and list-item query helpers
• Blocks
  • ✅ Headings, paragraphs, block quotes, callouts, fenced code, tables, lists, task lists, definition lists, front matter, footnotes, TOC placeholders
  • ✅ HTML comments, raw HTML blocks, horizontal rules, details/summary
• Inlines
  • ✅ Text, emphasis, strong, strike, highlight, code spans, links, images, reference links
  • ✅ Typed inline sequences and inline plain-text extraction
• Rendering
  • ✅ Markdown output
  • ✅ HTML fragment and full document output
  • ✅ Themes: Plain, Clean, GitHub Light/Dark/Auto, Chat Light/Dark/Auto, Word
  • ✅ TOC layouts: list, panel, sidebar left/right with sticky and ScrollSpy options
• Parsing
  • ✅ Typed reader with optional syntax tree
  • ✅ Portable profile for stricter, more neutral parsing defaults
  • ✅ Input normalization presets for transcript/chat/docs cleanup

Supported Markdown

Blocks

• headings
• paragraphs and hard breaks
• fenced code blocks with optional language and captions
• images with optional size hints
• unordered, ordered, task, and definition lists
• GitHub-style pipe tables
• block quotes with lazy continuation
• callouts
• horizontal rules
• footnotes
• front matter
• TOC placeholders

Inlines

• text
• emphasis / strong / combined emphasis
• strike and highlight
• code spans
• inline and reference links
• inline and linked images

HTML Rendering Notes

• ToHtmlFragment(...) is ideal for embedding into an existing page or WebView host.
• ToHtmlDocument(...) is ideal for standalone docs or generated reports.
• HtmlStyle.Word gives a document-like look with Word-style typography and table defaults.
• ToHtmlParts(...) exposes asset manifests for hosts that want to deduplicate or merge CSS/JS themselves.

Benchmarks

OfficeIMO.Markdown.Benchmarks ships in-repo as the benchmark harness used for release-prep sanity checks.

• representative parse workloads
• representative HTML-render workloads
• default reader behavior vs portable profile

For release steps, see ../Docs/officeimo.markdown.release-checklist.md.

Package Family

• OfficeIMO.Markdown: build, parse, query, and render Markdown/HTML
• OfficeIMO.MarkdownRenderer: host-oriented WebView/browser shell helpers built on top of OfficeIMO.Markdown
• OfficeIMO.Word.Markdown: Word conversion layer that uses the Markdown package family

Dependencies & Versions

• No runtime NuGet dependencies for the core markdown library
• Targets: netstandard2.0, net472, net8.0, net10.0
• License: MIT

Notes on Versioning

• Minor releases may add APIs, improve parser coverage, and broaden AST/query capabilities.
• Patch releases focus on correctness, compatibility, and rendering fixes.
• The current goal is a stable and intentional package baseline, not a frozen 1.0 contract yet.

Notes

• Cross-platform: no COM automation, no Office requirement
• Deterministic output is a design goal for tests, docs, and downstream exports
• Public API and docs are being actively polished ahead of the next package line