OfficeIMO.Markdown.Pdf 1.0.0

OfficeIMO.Markdown.Pdf

Markdown to PDF conversion for OfficeIMO.Markdown.

OfficeIMO.Markdown.Pdf is a thin adapter: it reads the typed Markdown object model and writes through the first-party OfficeIMO.Pdf engine. It does not add a separate rendering stack or runtime dependency.

Usage

using OfficeIMO.Markdown;
using OfficeIMO.Markdown.Pdf;

MarkdownDoc document = MarkdownReader.Parse("""
# Status

This is **important** and includes [OfficeIMO](https://github.com/EvotecIT/OfficeIMO).

| Area | State |
| --- | --- |
| PDF | Native |
""");

document.SaveAsPdf("status.pdf");

String overloads parse Markdown first:

using OfficeIMO.Markdown.Pdf;

"# Hello\n\nGenerated by OfficeIMO.".SaveAsPdf("hello.pdf");

File-based conversion uses explicit converter methods so a string path is never confused with Markdown text:

using OfficeIMO.Markdown.Pdf;

MarkdownPdfConverter.SaveFileAsPdf("README.md", "README.pdf");

Visual themes

Markdown has structure, but it has no native page style. The adapter applies a Word-like visual profile by default so generated PDFs have readable document rhythm, tables, panels, quotes, and callouts instead of looking like plain extracted text.

Built-in profiles:

• Plain
• WordLike
• TechnicalDocument
• GitHubLike
• Compact
• Report

Use a profile from code:

using OfficeIMO.Markdown.Pdf;

var options = new MarkdownPdfSaveOptions {
    VisualTheme = MarkdownPdfVisualTheme.TechnicalDocument()
};

MarkdownPdfConverter.SaveFileAsPdf("README.md", "README.pdf", options);

Or select one from YAML front matter:

---
title: Release Guide
pdfTheme: report
---

# Release Guide

The front matter key accepts pdfTheme or pdf-theme. Unknown values are reported through MarkdownPdfSaveOptions.Warnings and fall back to the configured default profile.

By default, front matter with a title is rendered as a polished document header instead of a literal YAML table. The same values still feed PDF metadata. Matching first-level headings are suppressed so this common pattern does not duplicate the title:

var options = new MarkdownPdfSaveOptions {
    FrontMatterRenderMode = MarkdownPdfFrontMatterRenderMode.DocumentHeader
};

Set FrontMatterRenderMode to Table for the previous key/value table output or Hidden when front matter should only affect metadata and theme selection.

Visual themes can also tune code and semantic fenced block typography:

MarkdownPdfVisualTheme theme = MarkdownPdfVisualTheme.TechnicalDocument();
theme.CodeBlockFontSize = 10;
theme.CodeBlockLabelColor = OfficeIMO.Pdf.PdfColor.FromRgb(9, 105, 218);

markdown.SaveAsPdf("guide.pdf", new MarkdownPdfSaveOptions {
    VisualTheme = theme
});

Ordinary Markdown links are part of the same visual layer. LinkColor and UnderlineLinks apply across paragraphs, lists, task-list rows, tables, panels, definitions, and footnotes; generated table-of-contents entries keep their separate TocLinkColor setting:

MarkdownPdfVisualTheme theme = MarkdownPdfVisualTheme.Report();
theme.LinkColor = OfficeIMO.Pdf.PdfColor.FromRgb(30, 64, 175);
theme.UnderlineLinks = false;

Theme profiles may also apply page-level treatment through the shared OfficeIMO.Pdf decoration primitives. For example, TechnicalDocument adds a quiet document frame and rule accents for guides, while Report adds a stronger background, page frame, and vector accent bands without requiring the Markdown source to carry presentation-only markup.

Page decoration is part of the visual theme and can be disabled or customized:

MarkdownPdfVisualTheme theme = MarkdownPdfVisualTheme.Report();
theme.PageDecoration = new MarkdownPdfPageDecoration {
    BackgroundColor = OfficeIMO.Pdf.PdfColor.White,
    PageBorder = new OfficeIMO.Pdf.PdfPageBorder {
        Color = OfficeIMO.Pdf.PdfColor.FromRgb(15, 118, 110),
        Width = 0.8,
        Inset = 28,
        Opacity = 0.5
    }
}.AddBackgroundShape(OfficeIMO.Pdf.PdfPageBackgroundShape.Rectangle(
    42,
    700,
    128,
    32,
    fill: OfficeIMO.Pdf.PdfColor.FromRgb(204, 251, 241),
    fillOpacity: 0.44));

Task lists use the same visual layer. Checked and unchecked items render as static vector checklist rows, and themes can customize the checkbox icon colors, row fills, and text colors without introducing PDF form fields:

MarkdownPdfVisualTheme theme = MarkdownPdfVisualTheme.GitHubLike();
theme.ChecklistCheckedIconColor = OfficeIMO.Pdf.PdfColor.FromRgb(26, 127, 55);
theme.ChecklistUncheckedIconColor = OfficeIMO.Pdf.PdfColor.FromRgb(87, 96, 106);
theme.ChecklistCheckedFillColor = OfficeIMO.Pdf.PdfColor.FromRgb(246, 248, 250);
theme.DocumentHeaderTitleFontSize = 26;
theme.DocumentHeaderRuleColor = OfficeIMO.Pdf.PdfColor.FromRgb(208, 215, 222);

Current conversion model

Supported mappings include:

• headings with bookmark anchors and PDF outlines
• PDF title/author/subject/keywords metadata from explicit options, YAML front matter, or the first heading
• YAML front matter as a theme-aware document header, a key/value table, or metadata-only hidden content
• paragraphs with bold, italic, underline, strike, highlight, code spans, hard breaks, theme-aware URI links, and heading-anchor links
• ordered and unordered lists, with task-list items rendered as theme-aware static vector PDF checklist rows instead of literal [x] / [ ] text
• pipe tables with rich inline cell content
• code blocks as Courier-styled panels
• semantic fenced blocks as labelled Courier-styled panels
• callouts and details blocks as first-party PDF panels, with common nested child blocks routed through the shared OfficeIMO.Pdf composed-panel surface instead of loose Markdown text
• definition lists as two-column PDF tables
• generated table-of-contents blocks with heading-anchor links
• footnote definition blocks as compact note paragraphs
• block quotes as shaded panels, including readable nested lists, tables, code, details, and child quotes when they fit the shared composed-panel model
• horizontal rules
• local JPEG/PNG images when the path can be resolved, self-contained base64 data:image/png and data:image/jpeg images, and opt-in HTTP/HTTPS image bytes supplied by MarkdownPdfSaveOptions.RemoteImageResolver
• built-in visual themes and front matter pdfTheme selection

Unsupported or simplified features are recorded in MarkdownPdfSaveOptions.Warnings.

Remote images are not downloaded automatically. Provide a resolver when the host application has a trusted fetch/cache policy:

var options = new MarkdownPdfSaveOptions {
    RemoteImageResolver = uri =>
        trustedImageCache.TryGetValue(uri, out byte[]? bytes) ? bytes : null,
    MaximumRemoteImageBytes = 2 * 1024 * 1024
};