MuPDF.NET.Examples

Customer-facing sample apps for MuPDF.NET 4.0 and MuPDF.NET.Office 2.0.2.

Markdown / JSON / text extract (Document.ToMarkdown, ToJson, ToText) and RAG helpers (LoadAiAsync, Llama, MarkdownToPdf) are in MuPDF.NET 4.0 (MuPDF.NET.PDF4LLM namespace inside MuPDF.NET.dll). The empty PDF4LLM NuGet stub is not used here. LLM samples stay under the MuPDF.NET.PDF4LLM/ folder so Input/Expected paths stay stable.

Each feature is a small console project. Packages are referenced via NuGet only.

Every Program.cs uses Main plus one named sample method (for example OpenSave()) with line comments so you can copy that method into your own project. Main only parses args and calls the sample.

Every example writes results under Output/ and compares them to golden files in that project’s Expected/ folder. Look for PASS — / FAIL — / SKIP — in the console. Use run-all.cmd, .\run-all.ps1, or ./run-all.sh to batch-test after NuGet upgrades (they key off those lines; Office samples may AV during process teardown after a successful PASS).

Clone and restore

git clone https://github.com/ArtifexSoftware/MuPDF.NET.Examples.git
cd MuPDF.NET.Examples
dotnet restore

Package versions are pinned in Versions.props. NuGet.Config restores Artifex packages from D:\Artifex\LocalNuget first, then the repo-local LocalNuget/ folder, then nuget.org.

Layout

Path	Role
Common/	Paths, ResultCheck, PDF fingerprints
Input/	Fixtures (committed)
Output/	Generated files (gitignored)
{product}/{NN-Name}/Expected/	Golden baselines (committed)
run-all.cmd / run-all.ps1 / run-all.sh	Batch PASS/FAIL/SKIP runner
LocalNuget/	Optional local .nupkg drop folder
LICENSE.md	Artifex Community License
SECURITY.md	Vulnerability reporting

Prerequisites

• .NET 8 SDK (Windows, Linux, or macOS)
• Packages from nuget.org (see Versions.props)
• Optional MUPDF_OFFICE_KEY for Office unlock
• 02-ToJsonLayout / 03-ToText: optional pymupdf 2.0 layout worker (dotnet msbuild -t:MuPDFNetSetupLayoutPython)
• 09-LoadAi: optional AZURE_OPENAI_* (and AZURE_SEARCH_*) for a live model; default run needs no keys
• 10-Ollama / 11-OllamaMagazines: local Ollama (ollama pull mistral and ollama pull nomic-embed-text); SKIP when Ollama is not running — see MuPDF.NET.PDF4LLM/10-Ollama/README.md

Run (compare against Expected/)

dotnet restore
.\run-all.cmd          # Windows
# or: .\run-all.ps1
# or one project:
dotnet run --project MuPDF.NET\01-OpenSave

# Linux / macOS (requires pwsh: https://aka.ms/powershell)
dotnet restore
chmod +x ./run-all.sh
./run-all.sh
# or: pwsh ./run-all.ps1
dotnet run --project MuPDF.NET/01-OpenSave

Refresh baselines after a trusted package upgrade

.\run-all.cmd --update-expected
# or: .\run-all.ps1 -UpdateExpected
# or:
dotnet run --project MuPDF.NET\01-OpenSave -- --update-expected

What is compared

Kind	Method
Markdown / JSON / text	Exact text (LF-normalized)
PNG	SHA-256
PDF	pageCount + SHA-256 of extracted text (not raw PDF bytes)
Unlock / page counts	Small *.summary.txt property files

Example projects

Each project folder has its own README.md (what it shows, inputs, how to run, APIs).

Naming tip — color vs images

Want to…	Use
Convert page to DeviceCMYK/RGB/Gray	05-Recolor
ICC soft proof, separations, overprint	19-ColorManagement
Place a new image on a page	09-InsertImage
Swap an existing image xref	17-ReplaceImage
Extract embedded images to files	21-ExtractImages
Downsample / recompress images	20-RewriteImages
Compress PDF streams on save	25-CompressSave
Page file attachment annot	30-FileAnnot (vs 13-EmbeddedFiles)
Render many files/pages in parallel	31-ParallelPixmap (vs sequential 03-RenderPixmap)

Product	Projects
MuPDF.NET	Open/Save, Pages, Render, Parallel pixmap, Text, Recolor, Story/HTML, Annotations, Widgets, Insert/Replace/Extract images, Outline/Links, Tables, Barcodes, Embedded files, Metadata, TextWriter, Draw shapes, ZUGFeRD, Color management, Rewrite images, GetDrawings, Rotate/Crop, Encrypt, Compress, Watermark, Image→PDF, Image filters, Page ops, File annot
MuPDF.NET (LLM / RAG, folder MuPDF.NET.PDF4LLM/)	Markdown, JSON layout, Plain text, OCR, Tables→CSV, Llama markdown reader, GetKeyValues, Markdown→PDF, LoadAi (RAG ask/search), Ollama capitals, Ollama magazines
MuPDF.NET.Office	Unlock/fonts, Open HWPX/DOCX, Export PDF, Export MD/JSON, Unlock then Document.ToMarkdown

Versions

Edit Versions.props only. Current pins: MuPDF.NET 4.0.0, Office 2.0.2. Restore looks in D:\Artifex\LocalNuget first, then LocalNuget/, then nuget.org.

License

See LICENSE.md (Artifex Community License). The NuGet packages these samples use have their own license terms on nuget.org / artifex.com.