Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/

Parse and Inspect Markdown Files

Edit on GitHub

Load Markdown into a typed model, list headings, read and edit YAML or TOML front matter, extract tables and code blocks, and check diagnostics.

Packages
Works with
  • .NET
  • PowerShell Install-Module PSWriteOffice
  • CLI dotnet tool install --global OfficeIMO.Tool
Target frameworks
netstandard2.0, net8.0, net10.0, net472
Limits
Math syntax ($...$) is parsed only when MarkdownLoadOptions.Math is enabled; front matter that is not valid YAML or TOML stays as text with a diagnostic. OfficeIMO.Markdown support matrix
Verified
Examples compiled against the source on

MarkdownDocument.Load reads a file and MarkdownDocument.Parse reads a string. Both return the same typed model: headings with their anchors, blocks such as TableBlock and CodeBlock, inline formatting, front matter and source spans. Use the model to validate documentation, extract data from Markdown reports, or make targeted edits and save the file back.

List headings and anchors

GetHeadingInfos returns every heading with its level, plain text and the anchor the HTML renderer will use.

C#

using OfficeIMO.Markdown;

MarkdownDocument document = MarkdownDocument.Parse("""
# User guide

## Install the package

## First steps
""");

foreach (MarkdownDocument.HeadingInfo heading in document.GetHeadingInfos()) {
    Console.WriteLine($"{new string(' ', (heading.Level - 1) * 2)}{heading.Text} -> #{heading.Anchor}");
}

MarkdownDocument.HeadingInfo? install = document.FindHeading("Install the package");
Console.WriteLine(install?.Anchor);
Console.WriteLine(document.HasHeadingAnchor("first-steps"));

PowerShell

Get-OfficeMarkdownHeading -Path .\README.md -MinLevel 2 |
    Select-Object Level, Text, Anchor

Read and edit front matter

Front matter between --- lines is YAML; between +++ lines it is TOML. Unedited front matter is written back byte for byte, and an edit rewrites only the value you change.

C#

using OfficeIMO.Markdown;

File.WriteAllText("post.md", """
---
title: Draft title
author:
  name: Ada
draft: true
---
# Post
""");

MarkdownDocument document = MarkdownDocument.Load("post.md");
FrontMatterBlock header = document.DocumentHeader!;

string? title = header.FindEntry("title")?.Value.AsString();
string? author = header.Select("author.name")?.AsString();
bool draft = header.TryGetValue("draft", out bool isDraft) && isDraft;
Console.WriteLine($"{title} by {author}, draft: {draft}");

header.Yaml!.Set("title", "Final title");
document.Save();

PowerShell

Get-OfficeMarkdownFrontMatter -Path .\post.md | Select-Object Key, Value
Get-OfficeMarkdownFrontMatter -Path .\post.md -Key 'title'

Extract tables and code blocks

DescendantTables and DescendantsOfType<T> walk the whole document, including content nested in lists, quotes and callouts.

C#

using OfficeIMO.Markdown;

MarkdownDocument document = MarkdownDocument.Parse("""
| Service | Status |
| --- | --- |
| API | Green |
| Jobs | Yellow |

~~~powershell
Get-Service
~~~
""");

foreach (TableBlock table in document.DescendantTables()) {
    Console.WriteLine(string.Join(" | ", table.Headers));
    foreach (IReadOnlyList<string> row in table.Rows) {
        Console.WriteLine(string.Join(" | ", row));
    }
}

foreach (CodeBlock code in document.DescendantsOfType<CodeBlock>()) {
    Console.WriteLine($"{code.Language}: {code.Content}");
}

PowerShell

Open-OfficeMarkdown -Path .\Report.md | Get-OfficeMarkdownTable -AsObject
Get-OfficeMarkdownNode -Path .\README.md -NodeType '*Code*'

Check parse diagnostics

Use the Load or Parse overload with out OfficeConversionReport when diagnostics, such as invalid front matter, must travel with the document.

C#

using OfficeIMO;
using OfficeIMO.Markdown;

MarkdownDocument document = MarkdownDocument.Parse("""
---
title: [unclosed
---
# Notes
""", null, out OfficeConversionReport report);

foreach (OfficeDiagnostic diagnostic in report.Diagnostics) {
    Console.WriteLine($"{diagnostic.Severity} {diagnostic.Code}: {diagnostic.Message}");
}

Console.WriteLine(document.GetHeadingInfos().Count);

Edit a parsed document and save it

Parsed documents use the same builder methods as new ones, so you can add missing sections and write the result.

C#

using OfficeIMO.Markdown;

File.WriteAllText("README.md", "# MyProject\n\nA data processing library.\n");

MarkdownDocument document = MarkdownDocument.Load("README.md");
if (!document.HasHeading("Install")) {
    document
        .H2("Install")
        .Code("sh", "dotnet add package MyProject");
}

document.Save("README.md");
Console.WriteLine(document.ToMarkdown());

PowerShell

$document = Open-OfficeMarkdown -Path .\README.md
$document | Add-OfficeMarkdownHeading -Level 2 -Text 'Install'
$document | Add-OfficeMarkdownCode -Language 'sh' -Text 'dotnet add package MyProject'
$document | Save-OfficeMarkdown
$document | Close-OfficeMarkdown

Read Markdown as text or JSON for indexing

The Reader turns a Markdown file into normalized Markdown or JSON chunks for search pipelines.

CLI

officeimo reader read README.md --format json --output README.json

Example source