# Parse and Inspect Markdown Files

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**

- [OfficeIMO.Markdown](https://www.nuget.org/packages/OfficeIMO.Markdown) `dotnet add package OfficeIMO.Markdown`

**Works with**

- .NET
- [PowerShell](/docs/pswriteoffice/install/) `Install-Module PSWriteOffice`
- [CLI](/docs/cli/install/) `dotnet tool install --global OfficeIMO.Tool`

**Target frameworks**

netstandard2.0, net8.0, net10.0, net472

**APIs**

- [`MarkdownDocument`](/api/markdown/officeimo-markdown-markdowndocument/)
- [`CodeBlock`](/api/markdown/officeimo-markdown-codeblock/)
- [`OfficeConversionReport`](/api/core/officeimo-officeconversionreport/)
- [`TableBlock`](/api/markdown/officeimo-markdown-tableblock/)
- [`FrontMatterBlock`](/api/markdown/officeimo-markdown-frontmatterblock/)
- [`OfficeDiagnostic`](/api/core/officeimo-officediagnostic/)

**Cmdlets**

- [`Open-OfficeMarkdown`](/api/powershell/open-officemarkdown/)
- [`Get-OfficeMarkdownHeading`](/api/powershell/get-officemarkdownheading/)
- [`Get-OfficeMarkdownFrontMatter`](/api/powershell/get-officemarkdownfrontmatter/)
- [`Get-OfficeMarkdownTable`](/api/powershell/get-officemarkdowntable/)
- [`Get-OfficeMarkdownNode`](/api/powershell/get-officemarkdownnode/)
- [`Save-OfficeMarkdown`](/api/powershell/save-officemarkdown/)

**Commands**

- [`officeimo reader read`](/docs/cli/extract-and-inspect/)

**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](/compatibility/#package-markdown)

**Verified**

Examples compiled against the source on 2026-11-14

**Data**

- [OfficeIMO.Markdown API index](/api/markdown/index.json)
- [PSWriteOffice command catalog](/data/powershell/commands.json)
- [CLI command catalog](/data/cli/commands.json)
- [Capability catalog (JSON)](/data/capabilities.json)

`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#

```csharp
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

```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#

```csharp
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

```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#

```csharp
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

```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#

```csharp
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#

```csharp
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

```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

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

<!-- PowerForge markdown source sha256:7DA8384CC28AA46480764A2FB3128585048F7CB5D5C0181E03370AE7BA4F826C; title=True -->

<!-- PowerForge markdown artifact sha256:9F5A60512015C439F4A916F272CD6F755C1A8B8C876D12A4A33945550843583D -->
