Pmad.Markitdown 0.0.2

Pmad.Markitdown

A lightweight, pure managed .NET library to convert documents (HTML, PDF, DOCX, and plain text) into clean Markdown with zero external or Docker dependencies.

Targeting .NET 10 and .NET 8.

Features

• Pure .NET (Managed): Runs fully in-process. No Python, no Docker, no Node.js required.
• HTML to Markdown:
  • Full DOM parsing and sanitization powered by AngleSharp.
  • High-fidelity Markdown generation powered by ReverseMarkdown.
  • Automatically extracts <title> as a top-level # heading if not already present.
  • Strips noisy boilerplate elements (<script>, <style>, <nav>, <svg>, <footer>).
• PDF to Markdown:
  • Extracted via PdfPig (Apache-2.0).
  • Robust text and structure extraction handling font CMaps, subsetted fonts, and reading order layout analysis.
• Word (DOCX) to Markdown:
  • Semantic document extraction via Mammoth piped into clean Markdown.
• Plain Text / Code / JSON:
  • Line ending and encoding normalization.
• Extensible Architecture:
  • Implements a pluggable converter strategy (IFormatConverter) allowing custom formats to be easily registered.

Installation

Install via NuGet:

dotnet add package Pmad.Markitdown

Or via Package Manager Console:

Install-Package Pmad.Markitdown

Quick Start

1. Basic Conversion

using Pmad.Markitdown;

IMarkitdown markitdown = new Markitdown();

// Convert a local file (.html, .pdf, .docx, .txt, etc.)
string markdown = await markitdown.ConvertFileAsync("document.pdf");
Console.WriteLine(markdown);

2. Convert from a Stream

Pass a Stream alongside a file extension or MIME media type:

using var stream = File.OpenRead("report.docx");

// By extension
string mdFromDocx = await markitdown.ConvertAsync(stream, ".docx");

// Or by MIME type
string mdFromPdf = await markitdown.ConvertAsync(pdfStream, "application/pdf");

3. Convert Raw HTML or Text

string html = "<html><head><title>My Article</title></head><body><p>Hello <strong>World</strong>!</p></body></html>";

string markdown = await markitdown.ConvertTextAsync(html, "text/html");
// Output:
// # My Article
//
// Hello **World**!

Configuration Options

Customize conversion behavior using MarkitdownOptions:

var options = new MarkitdownOptions
{
    // Extract document title as an H1 heading if missing from the body (default: true)
    IncludeTitle = true,

    // Strip scripts, styles, navigation, and footer tags from HTML (default: true)
    CleanHtml = true,

    // Resolve relative links and images into absolute URLs (default: null)
    BaseUrl = new Uri("https://example.com/")
};

string markdown = await markitdown.ConvertFileAsync("article.html", options);

You can also pass default options directly to the Markitdown constructor:

var markitdown = new Markitdown(new MarkitdownOptions
{
    IncludeTitle = false
});

Dependency Injection

Register Pmad.Markitdown in your IServiceCollection:

// Program.cs
builder.Services.AddSingleton<IMarkitdown, Markitdown>();

Inject and use in your services:

public class DocumentProcessor
{
    private readonly IMarkitdown _markitdown;

    public DocumentProcessor(IMarkitdown markitdown)
    {
        _markitdown = markitdown;
    }

    public async Task ProcessAsync(Stream stream, string contentType)
    {
        string markdown = await _markitdown.ConvertAsync(stream, contentType);
        // ...
    }
}

Adding Custom Format Converters

You can extend Pmad.Markitdown with your own custom converters by implementing IFormatConverter:

using Pmad.Markitdown.Converters;

public class CustomCsvConverter : IFormatConverter
{
    public bool CanHandle(string? extension, string? mediaType) =>
        string.Equals(extension, ".csv", StringComparison.OrdinalIgnoreCase) ||
        string.Equals(mediaType, "text/csv", StringComparison.OrdinalIgnoreCase);

    public async Task<string> ConvertAsync(Stream stream, MarkitdownOptions options, CancellationToken cancellationToken)
    {
        using var reader = new StreamReader(stream);
        var csv = await reader.ReadToEndAsync(cancellationToken);
        // Convert CSV to Markdown table...
        return "| Header 1 | Header 2 |\n| --- | --- |\n";
    }
}

// Register custom converters:
var converters = new IFormatConverter[]
{
    new CustomCsvConverter(),
    new HtmlToMarkdownConverter(),
    new PdfToMarkdownConverter()
};

var markitdown = new Markitdown(converters);

Supported Formats

License

This project is licensed under the MIT License.