KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

ElBruno.MarkItDotNet

★ 48 Open GitHub ↗

.NET library that converts file formats to Markdown for AI pipelines

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ElBruno.MarkItDotNet

[![Build](https://github.com/elbruno/ElBruno.MarkItDotNet/actions/workflows/ci.yml/badge.svg)](https://github.com/elbruno/ElBruno.MarkItDotNet/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/elbruno/ElBruno.MarkItDotNet/main/LICENSE)

**.NET library that converts 15+ file formats to Markdown** for AI pipelines, documentation workflows, and developer tools. Inspired by Python [markitdown](https://github.com/microsoft/markitdown).

## 📦 NuGet Packages

| Package | Version | Downloads | Description |
| --------- | --------- | ----------- | ------------- |
| [ElBruno.MarkItDotNet](https://www.nuget.org/packages/ElBruno.MarkItDotNet) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet) | Core library — 12 built-in converters |
| [ElBruno.MarkItDotNet.Excel](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Excel) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.Excel.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Excel) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.Excel.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Excel) | Excel (.xlsx) → Markdown tables |
| [ElBruno.MarkItDotNet.PowerPoint](https://www.nuget.org/packages/ElBruno.MarkItDotNet.PowerPoint) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.PowerPoint.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.PowerPoint) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.PowerPoint.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.PowerPoint) | PowerPoint (.pptx) → slides + notes |
| [ElBruno.MarkItDotNet.AI](https://www.nuget.org/packages/ElBruno.MarkItDotNet.AI) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.AI.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.AI) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.AI.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.AI) | AI-powered OCR, captioning, transcription |
| [ElBruno.MarkItDotNet.Whisper](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Whisper) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.Whisper.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Whisper) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.Whisper.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Whisper) | Local audio transcription via Whisper ONNX |
| [ElBruno.MarkItDotNet.Security](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Security) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.Security.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Security) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.Security.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Security) | Markdown security scanning and issue reporting |
| [ElBruno.MarkItDotNet.Evals](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Evals) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.Evals.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Evals) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.Evals.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Evals) | Conversion quality evaluation and scoring |
| [ElBruno.MarkItDotNet.Cli](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Cli) | [![NuGet](https://img.shields.io/nuget/v/ElBruno.MarkItDotNet.Cli.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Cli) | [![Downloads](https://img.shields.io/nuget/dt/ElBruno.MarkItDotNet.Cli.svg?style=flat-square)](https://www.nuget.org/packages/ElBruno.MarkItDotNet.Cli) | Command-line tool (`markitdown-dotnet` command) |

## Description

ElBruno.MarkItDotNet provides a unified interface to convert 15+ file formats into clean, structured Markdown. The core package handles text, JSON, HTML, Word, PDF, RTF, EPUB, images, CSV, XML, YAML, and **URLs (web pages)**. Extend with satellite packages for Excel, PowerPoint, AI-powered features (OCR, image captioning, audio transcription), and **local audio transcription via Whisper**. Designed for AI content pipelines, documentation systems, and any scenario where you need consistent Markdown output from mixed file sources.

## Supported Formats

| Format | Extensions | Converter | Package | Dependencies |
| -------- | ----------- | ----------- | --------- | --- |
| Plain Text | `.txt`, `.md`, `.log` | `PlainTextConverter` | Core | None |
| JSON | `.json` | `JsonConverter` | Core | None |
| HTML | `.html`, `.htm` | `HtmlConverter` | Core | `ReverseMarkdown` |
| URL (Web Pages) | `.url` | `UrlConverter` | Core | `ReverseMarkdown` |
| Word (DOCX) | `.docx` | `DocxConverter` | Core | `DocumentFormat.OpenXml` |
| PDF | `.pdf` | `PdfConverter` | Core | `PdfPig` |
| CSV / TSV | `.csv`, `.tsv` | `CsvConverter` | Core | None |
| XML | `.xml` | `XmlConverter` | Core | None |
| YAML | `.yaml`, `.yml` | `YamlConverter` | Core | None |
| RTF | `.rtf` | `RtfConverter` | Core | `RtfPipe` |
| EPUB | `.epub` | `EpubConverter` | Core | `VersOne.Epub` |
| Images | `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.webp`, `.svg` | `ImageConverter` | Core | None |
| Excel (XLSX) | `.xlsx` | `ExcelConverter` | **Excel** | `ClosedXML` |
| PowerPoint (PPTX) | `.pptx` | `PowerPointConverter` | **PowerPoint** | `DocumentFormat.OpenXml` |
| Images (AI-OCR) | All image formats | `AiImageConverter` | **AI** | `Microsoft.Extensions.AI` |
| Audio (AI Transcription) | `.mp3`, `.wav`, `.m4a`, `.ogg` | `AiAudioConverter` | **AI** | `Microsoft.Extensions.AI` |
| PDF (AI-OCR) | `.pdf` | `AiPdfConverter` | **AI** | `Microsoft.Extensions.AI` |
| Audio (Local Whisper) | `.wav`, `.mp3`, `.m4a`, `.ogg`, `.flac` | `WhisperAudioConverter` | **Whisper** | `ElBruno.Whisper` |

## Target Frameworks

- .NET 8.0 (LTS)
- .NET 10.0

## 🛠️ CLI Tool

**Command-line interface for batch conversion and terminal workflows.**

### Installation

Install as a global tool:

```bash
dotnet tool install -g ElBruno.MarkItDotNet.Cli
```

### Quick Examples

Convert a single file:

> **⚠️ v0.9.0 Breaking Change — CLI command renamed**
> The command has been renamed from `markitdown` to `markitdown-dotnet` to avoid collision with the [Microsoft Python markitdown CLI](https://github.com/microsoft/markitdown). To upgrade: `dotnet tool update -g ElBruno.MarkItDotNet.Cli` — then use `markitdown-dotnet` instead of `markitdown`.

```bash
markitdown-dotnet report.pdf
markitdown-dotnet report.pdf -o report.md
```

Batch convert a directory:

```bash
markitdown-dotnet batch ./documents -o ./output -r --pattern "*.pdf"
```

Convert a web page:

```bash
markitdown-dotnet url https://example.com -o page.md
```

Extract metadata as JSON:

```bash
markitdown-dotnet data.csv --format json | jq .metadata.wordCount
```

**→ [Full CLI Documentation](docs/cli.md)**

## Packages

ElBruno.MarkItDotNet is distributed across multiple NuGet packages for flexibility:

### Core Package

**ElBruno.MarkItDotNet** — The main library with 12 built-in converters.

```bash
dotnet add package ElBruno.MarkItDotNet
```

Includes: Plain text, JSON, HTML, **URLs (web pages)**, Word, PDF, RTF, EPUB, images, CSV, XML, YAML.

### Satellite Packages

**ElBruno.MarkItDotNet.Excel** — Excel (XLSX) to Markdown converter (v0.2.0+)

```bash
dotnet add package ElBruno.MarkItDotNet.Excel
```

Converts spreadsheet sheets to Markdown tables.

**ElBruno.MarkItDotNet.PowerPoint** — PowerPoint (PPTX) to Markdown converter (v0.2.0+)

```bash
dotnet add package ElBruno.MarkItDotNet.PowerPoint
```

Converts slides and speaker notes to Markdown.

**ElBruno.MarkItDotNet.AI** — AI-powered converters (v0.2.0+)

```bash
dotnet add package ElBruno.MarkItDotNet.AI
```

Requires `Microsoft.Extensions.AI` (for `IChatClient`). Provides:

- **AiImageConverter** — OCR for images using LLM vision
- **AiPdfConverter** — OCR for PDFs using LLM vision
- **AiAudioConverter** — Transcription for audio files using LLM audio APIs

**ElBruno.MarkItDotNet.Whisper** — Local audio transcription via Whisper ONNX (v0.3.0+)

```bash
dotnet add package ElBruno.MarkItDotNet.Whisper
```

Uses [ElBruno.Whisper](https://www.nuget.org/packages/ElBruno.Whisper) for offline speech-to-text. No cloud API needed — runs locally via ONNX Runtime. Supports `.wav`, `.mp3`, `.m4a`, `.ogg`, `.flac`.

**ElBruno.MarkItDotNet.Security** — Security scanning helpers for Markdown output.

```bash
dotnet add package ElBruno.MarkItDotNet.Security
```

Provides a configurable scanner to detect JavaScript links, secret-like tokens, and control characters with scored scan results.

**ElBruno.MarkItDotNet.Evals** — Conversion evaluation helpers for quality gates.

```bash
dotnet add package ElBruno.MarkItDotNet.Evals
```

Provides heuristic scoring, issue reporting, and retention-oriented metrics to support post-conversion validation.

**ElBruno.MarkItDotNet.Connectors** — Connector abstractions and file system source ingestion.

```bash
dotnet add package ElBruno.MarkItDotNet.Connectors
```

Provides the `IDocumentSource` contract, `SourceDocument`, and `FileSystemConnector`.

**ElBruno.MarkItDotNet.Connectors.AzureBlob** — Azure Blob source ingestion connector.

```bash
dotnet add package ElBruno.MarkItDotNet.Connectors.AzureBlob
```

Provides `AzureBlobConnector` with prefix filtering, paging options, and `DefaultAzureCredential` support.

## Core Library Installation

For the core library only:

```bash
dotnet add package ElBruno.MarkItDotNet
```

For Excel support:

```bash
dotnet add package ElBruno.MarkItDotNet.Excel
```

For PowerPoint support:

```bash
dotnet add package ElBruno.MarkItDotNet.PowerPoint
```

For AI-powered features (requires separate `IChatClient` registration):

```bash
dotnet add package ElBruno.MarkItDotNet.AI
```

For local audio transcription (offline, no API key needed):

```bash
dotnet add package ElBruno.MarkItDotNet.Whisper
```

For security scanning helpers:

```bash
dotnet add package ElBruno.MarkItDotNet.Security
```

For conversion evaluation helpers:

```bash
dotnet add package ElBruno.MarkItDotNet.Evals
```

For connector abstractions and filesystem ingestion:

```bash
dotnet add package ElBruno.MarkItDotNet.Connectors
```

For Azure Blob ingestion:

```bash
dotnet add package ElBruno.MarkItDotNet.Connectors.AzureBlob
```

## Quick Start

The simplest way to get started is with the `MarkdownConverter` façade:

```csharp
using ElBruno.MarkItDotNet;

var converter = new MarkdownConverter();

// Synchronous: Convert a file by path
var markdown = converter.ConvertToMarkdown("document.txt");
Console.WriteLine(markdown);
```

Or use asynchronous methods:

```csharp
// Asynchronous: Convert a file by path
var markdown = await converter.ConvertAsync("document.pdf");
Console.WriteLine(markdown);

// Asynchronous: Convert from a stream (provide file extension)
using var stream = File.OpenRead("document.pdf");
var markdownFromStream = await converter.ConvertAsync(stream, ".pdf");
Console.WriteLine(markdownFromStream);
```

The `MarkdownConverter` class pre-registers all built-in converters (from the core package) and provides synchronous and asynchronous conversion methods.

### URL Conversion

Convert web pages directly to Markdown:

```csharp
var service = new MarkdownService(registry);
var result = await service.ConvertUrlAsync("https://example.com");
Console.WriteLine(result.Markdown);
```

The URL converter fetches the page, strips navigation/scripts/styles, extracts the title, and converts the content to clean Markdown.

### With Satellite Packages

When you install satellite packages (Excel, PowerPoint, AI), converters are automatically registered during dependency injection setup. The system discovers them via the plugin system.

## Dependency Injection with Plugin System

For advanced scenarios (e.g., ASP.NET Core applications), use the DI extension methods to register MarkItDotNet services:

```csharp
using Microsoft.Extensions.DependencyInjection;
using ElBruno.MarkItDotNet;
using ElBruno.MarkItDotNet.Excel;
using ElBruno.MarkItDotNet.Evals;
using ElBruno.MarkItDotNet.PowerPoint;
using ElBruno.MarkItDotNet.Security;

var services = new ServiceCollection();

// Register core MarkItDotNet with built-in converters
services.AddMarkItDotNet();

// Register satellite package converters (plugins)
services.AddMarkItDotNetExcel();
services.AddMarkItDotNetPowerPoint();
services.AddMarkItDotNetSecurity();
services.AddMarkItDotNetEvals();

// Register AI converters (requires IChatClient)
// services.AddMarkItDotNetAI();

var provider = services.BuildServiceProvider();
var markdownService = provider.GetRequiredService<MarkdownService>();

// Convert files through the service (converters auto-discovered)
var result = await markdownService.ConvertAsync("document.xlsx");
if (result.Success)
{
    Console.WriteLine(result.Markdown);
}
else
{
    Console.WriteLine($"Error: {result.ErrorMessage}");
}
```

All registered converters (core + plugins) are automatically available through the `MarkdownService`.

## Streaming Conversion

For large files, use the streaming API to process content chunk-by-chunk:

```csharp
var converter = new MarkdownConverter();
using var stream = File.OpenRead("large-document.pdf");

await foreach (var chunk in converter.ConvertStreamingAsync(stream, ".pdf"))
{
    Console.Write(chunk);
}
```

The streaming API yields Markdown chunks asynchronously (e.g., page-by-page for PDFs), enabling memory-efficient processing of large files.

## AI-Powered Conversion

The `ElBruno.MarkItDotNet.AI` package provides converters that use LLM vision and audio APIs for advanced capabilities:

### Setup

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.AI;
using ElBruno.MarkItDotNet;
using ElBruno.MarkItDotNet.AI;

var services = new ServiceCollection();

// Register a chat client (e.g., OpenAI)
services.AddOpenAIChatClient("sk-...", "gpt-4-vision");

// Register core + AI converters
services.AddMarkItDotNet();
services.AddMarkItDotNetAI();

var provider = services.BuildServiceProvider();
var markdownService = provider.GetRequiredService<MarkdownService>();

// Use AI converters transparently
var result = await markdownService.ConvertAsync("screenshot.png");
Console.WriteLine(result.Markdown);
```

### AI Converters

- **AiImageConverter** — Uses LLM vision to describe images and extract text
- **AiPdfConverter** — Uses LLM vision to OCR PDFs (complements plain text extraction)
- **AiAudioConverter** — Uses LLM audio APIs to transcribe audio files (MP3, WAV, M4A, OGG)

Configure behavior via `AiOptions`:

```csharp
services.AddMarkItDotNetAI(options =>
{
    options.ImageDescriptionPrompt = "Describe this image in detail...";
    options.MaxRetries = 3;
});
```

## Local Audio Transcription (Whisper)

The `ElBruno.MarkItDotNet.Whisper` package uses [ElBruno.Whisper](https://www.nuget.org/packages/ElBruno.Whisper) for offline speech-to-text powered by ONNX Runtime. No cloud API needed.

```csharp
using ElBruno.Whisper;
using ElBruno.MarkItDotNet;
using ElBruno.MarkItDotNet.Whisper;

// Create Whisper client (downloads model on first run ~75MB)
using var whisperClient = await WhisperClient.CreateAsync();

// Register the plugin
var registry = new ConverterRegistry();
registry.RegisterPlugin(new WhisperConverterPlugin(whisperClient));

var service = new MarkdownService(registry);
var result = await service.ConvertAsync("recording.wav");
Console.WriteLine(result.Markdown);
```

Or with DI:

```csharp
services.AddMarkItDotNet();
services.AddMarkItDotNetWhisper(options =>
{
    options.Model = KnownWhisperModels.WhisperBaseEn; // Optional: pick model size
});
```

## API Reference

### MarkdownConverter

The public convenience façade for simple (non-DI) scenarios. Pre-registers all built-in converters.

```csharp
public class MarkdownConverter
{
    // Synchronous file conversion
    public string ConvertToMarkdown(string filePath, CancellationToken cancellationToken = default);

// Asynchronous file conversion by path
    public Task<string> ConvertAsync(string filePath, CancellationToken cancellationToken = default);

// Asynchronous stream conversion (requires explicit file extension)
    public Task<string> ConvertAsync(Stream stream, string fileExtension, CancellationToken cancellationToken = default);
}
```

All methods return the Markdown text directly. On unsupported formats, they throw `NotSupportedException`.

### MarkdownService

The main service for converting files to Markdown. Use this in DI scenarios or when you need advanced control over converters.

```csharp
public class MarkdownService
{
    public MarkdownService(ConverterRegistry registry);
    
    // Convert a file at the given path
    public Task<ConversionResult> ConvertAsync(string filePath);
    
    // Convert from a stream with explicit file extension
    public Task<ConversionResult> ConvertAsync(Stream stream, string fileExtension);
    
    // Stream conversion for large files
    public IAsyncEnumerable<string> ConvertStreamingAsync(Stream stream, string fileExtension);
}
```

### ConversionResult

Represents the outcome of a file conversion. Always check `Success` before accessing `Markdown`.

```csharp
public class ConversionResult
{
    public string Markdown { get; }          // Converted content (empty if failed)
    public string SourceFormat { get; }      // Source format (e.g., ".pdf")
    public bool Success { get; }             // Whether conversion succeeded
    public string? ErrorMessage { get; }     // Error details if Success is false
}
```

### IMarkdownConverter

Contract for implementing custom converters.

```csharp
public interface IMarkdownConverter
{
    // Check if this converter handles the given file extension
    bool CanHandle(string fileExtension);
    
    // Perform the conversion (extension includes the leading dot)
    Task<string> ConvertAsync(Stream fileStream, string fileExtension);
}
```

### IStreamingMarkdownConverter

Extended contract for converters that support streaming (chunk-by-chunk processing).

```csharp
public interface IStreamingMarkdownConverter : IMarkdownConverter
{
    // Converts content to Markdown, yielding chunks asynchronously
    IAsyncEnumerable<string> ConvertStreamingAsync(
        Stream fileStream,
        string fileExtension,
        CancellationToken cancellationToken = default);
}
```

### IConverterPlugin

Contract for plugin packages that bundle one or more converters.

```csharp
public interface IConverterPlugin
{
    // Human-readable name of the plugin (e.g., "Excel", "AI")
    string Name { get; }
    
    // Returns all converters provided by this plugin
    IEnumerable<IMarkdownConverter> GetConverters();
}
```

### ConverterRegistry

Manages and resolves converters by file extension.

```csharp
public class ConverterRegistry
{
    public void Register(IMarkdownConverter converter);
    public void RegisterPlugin(IConverterPlugin plugin);
    public IMarkdownConverter? Resolve(string extension);
    public IReadOnlyList<IMarkdownConverter> GetAll();
}
```

## Custom Converters

You can implement custom converters for unsupported file formats by implementing `IConverterPlugin` or `IMarkdownConverter`:

### Quick Custom Converter

Implement `IMarkdownConverter` for a single format:

```csharp
using ElBruno.MarkItDotNet;
using System.Text;

public class CsvConverter : IMarkdownConverter
{
    public bool CanHandle(string fileExtension) =>
        fileExtension.Equals(".csv", StringComparison.OrdinalIgnoreCase);

public async Task<string> ConvertAsync(Stream fileStream, string fileExtension)
    {
        using var reader = new StreamReader(fileStream, leaveOpen: true);
        var csv = await reader.ReadToEndAsync();
        
        var lines = csv.Split('\n');
        if (lines.Length == 0) return string.Empty;
        
        var sb = new StringBuilder();
        
        // Header row
        var headers = lines[0].Split(',');
        sb.Append("| ");
        sb.Append(string.Join(" | ", headers));
        sb.AppendLine(" |");
        sb.Append("|");
        sb.Append(string.Concat(headers.Select(_ => " --- |")));
        sb.AppendLine();
        
        // Data rows
        for (int i = 1; i < lines.Length; i++)
        {
            if (string.IsNullOrWhiteSpace(lines[i])) continue;
            var cells = lines[i].Split(',');
            sb.Append("| ");
            sb.Append(string.Join(" | ", cells));
            sb.AppendLine(" |");
        }
        
        return sb.ToString();
    }
}
```

```csharp
services.AddMarkItDotNet();
var registry = provider.GetRequiredService<ConverterRegistry>();
registry.Register(new CsvConverter());
```

### Satellite Plugin Package

For reusable plugins, implement `IConverterPlugin`:

```csharp
using ElBruno.MarkItDotNet;

public class MyCustomPlugin : IConverterPlugin
{
    public string Name => "MyCustom";

public IEnumerable<IMarkdownConverter> GetConverters() =>
    [
        new MyFormatConverter1(),
        new MyFormatConverter2()
    ];
}
```

```csharp
services.AddSingleton<IConverterPlugin>(new MyCustomPlugin());
```

The registry automatically discovers and loads all registered plugins.

## 📦 Samples

See the `src/samples/` projects below for detailed walkthroughs.

### Simple Samples

| Sample | Description | Run Command |
| -------- | ------------- | ------------- |
| [BasicConversion](src/samples/BasicConversion) | Text, JSON, and HTML conversion with DI | `dotnet run --project src/samples/BasicConversion/BasicConversion.csproj` |
| [CsvConversion](src/samples/CsvConversion) | CSV and TSV → Markdown tables | `dotnet run --project src/samples/CsvConversion/CsvConversion.csproj` |
| [XmlYamlConversion](src/samples/XmlYamlConversion) | XML and YAML → fenced code blocks | `dotnet run --project src/samples/XmlYamlConversion/XmlYamlConversion.csproj` |
| [PdfConversion](src/samples/PdfConversion) | PDF → Markdown with page metadata + streaming | `dotnet run --project src/samples/PdfConversion/PdfConversion.csproj` |
| [DocxConversion](src/samples/DocxConversion) | DOCX → Markdown with headings, tables, links | `dotnet run --project src/samples/DocxConversion/DocxConversion.csproj` |
| [RtfEpubConversion](src/samples/RtfEpubConversion) | RTF and EPUB → Markdown | `dotnet run --project src/samples/RtfEpubConversion/RtfEpubConversion.csproj` |
| [ExcelConversion](src/samples/ExcelConversion) | Excel .xlsx → Markdown tables (Excel package) | `dotnet run --project src/samples/ExcelConversion/ExcelConversion.csproj` |
| [PowerPointConversion](src/samples/PowerPointConversion) | PPTX slides + notes → Markdown (PowerPoint package) | `dotnet run --project src/samples/PowerPointConversion/PowerPointConversion.csproj` |
| [AiImageDescription](src/samples/AiImageDescription) | Image OCR/captioning via IChatClient (AI package) | `dotnet run --project src/samples/AiImageDescription/AiImageDescription.csproj` |
| [StreamingConversion](src/samples/StreamingConversion) | IAsyncEnumerable streaming for large PDFs | `dotnet run --project src/samples/StreamingConversion/StreamingConversion.csproj` |
| [CustomConverter](src/samples/CustomConverter) | Build a custom IMarkdownConverter (.ini files) | `dotnet run --project src/samples/CustomConverter/CustomConverter.csproj` |
| [PluginPackage](src/samples/PluginPackage) | Build and register a custom IConverterPlugin | `dotnet run --project src/samples/PluginPackage/PluginPackage.csproj` |
| [AllFormats](src/samples/AllFormats) | Converts all supported formats in one app | `dotnet run --project src/samples/AllFormats/AllFormats.csproj` |
| [UrlConversion](src/samples/UrlConversion) | Web page URL → Markdown | `dotnet run --project src/samples/UrlConversion/UrlConversion.csproj` |
| [WhisperTranscription](src/samples/WhisperTranscription) | Local audio transcription via Whisper ONNX | `dotnet run --project src/samples/WhisperTranscription/WhisperTranscription.csproj` |

### End-to-End Samples

| Sample | Description | Run Command |
| -------- | ------------- | ------------- |
| [BatchProcessor](src/samples/BatchProcessor) | Watches folder and batch-converts files to .md | `dotnet run --project src/samples/BatchProcessor/BatchProcessor.csproj` |
| [ConnectorsDemo](src/samples/ConnectorsDemo) | FileSystem + optional Azure Blob ingestion with source-separated outputs (`--dry-run` supported) | `dotnet run --project src/samples/ConnectorsDemo/ConnectorsDemo.csproj -- --dry-run` |
| [EvaluationDemo](src/samples/EvaluationDemo) | Benchmark-style strategy comparison with latency/memory metrics and JSON/CSV export (`--dry-run` supported) | `dotnet run --project src/samples/EvaluationDemo/EvaluationDemo.csproj -- --dry-run` |
| [IngestionWorkflow](src/samples/IngestionWorkflow) | End-to-end pipeline with connectors + security + evaluation + chunking + citations + optional Azure Search upload (`--dry-run` supported) | `dotnet run --project src/samples/IngestionWorkflow/IngestionWorkflow.csproj -- --dry-run` |
| [SecurityPoliciesDemo](src/samples/SecurityPoliciesDemo) | Configurable security policy chain with PII redaction and JSONL audit output (`--dry-run` supported) | `dotnet run --project src/samples/SecurityPoliciesDemo/SecurityPoliciesDemo.csproj -- --dry-run` |
| [RagPipeline](src/samples/RagPipeline) | RAG ingestion: files → Markdown → chunked JSON | `dotnet run --project src/samples/RagPipeline/RagPipeline.csproj` |
| [MarkItDotNet.FoundryHostedAgent](src/samples/MarkItDotNet.FoundryHostedAgent) | Hosted agent service + Aspire AppHost reference for Foundry deployment | `dotnet run --project src/samples/MarkItDotNet.FoundryHostedAgent/MarkItDotNet.FoundryHostedAgent.csproj` |

## Documentation

- [Roadmap / Ingestion PRD](docs/ElBruno.MarkItDotNet-Ingestion-PRD.md) — current implementation plan and remaining feature gaps
- [Architecture](docs/architecture.md) — design decisions, plugin system, converter pipeline, and internal structure
- [Connectors Guide](docs/connectors-guide.md) — `IDocumentSource`, FileSystem connector, Azure Blob connector, and DI wiring
- [Evaluation Guide](docs/evaluation-guide.md) — using `IEvaluationEngine` and interpreting evaluation reports
- [Ingestion Workflows](docs/ingestion-workflows.md) — end-to-end workflow composition across connectors, conversion, security, and evaluation
- [Security Guide](docs/security.md) — threat model, controls, and secure usage recommendations
- [Security Policies Guide](docs/security-policies-guide.md) — policy chains, redaction behavior, and audit output patterns
- [Plugins Guide](docs/plugins.md) — how to create custom plugin packages
- [Building & Testing](docs/building-and-testing.md) — how to build from source and run tests
- [Archived Docs](docs/archived/README.md) — historical plans, audits, and non-active documentation

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Security

ElBruno.MarkItDotNet processes untrusted file content and includes built-in security protections:

- **SSRF Protection** — URL converter blocks private/internal IP addresses
- **File Size Limits** — Configurable maximum file size (default 100MB)
- **XXE Prevention** — XML parser explicitly prohibits DTD processing
- **Prompt Injection Mitigation** — AI converters use system/user message separation

For detailed security guidance, see [docs/security.md](docs/security.md).

To report a security vulnerability, please use [GitHub Security Advisories](https://github.com/elbruno/ElBruno.MarkItDotNet/security/advisories).

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

## 👋 About the Author

Hi! I'm **ElBruno** 🧡, a passionate developer and content creator exploring AI, .NET, and modern development practices.

**Made with ❤️ by [ElBruno](https://github.com/elbruno)**

If you like this project, consider following my work across platforms:

- 📻 **Podcast**: [No Tienen Nombre](https://notienenombre.com) — Spanish-language episodes on AI, development, and tech culture
- 💻 **Blog**: [ElBruno.com](https://elbruno.com) — Deep dives on embeddings, RAG, .NET, and local AI
- 📺 **YouTube**: [youtube.com/elbruno](https://www.youtube.com/elbruno) — Demos, tutorials, and live coding
- 🔗 **LinkedIn**: [@elbruno](https://www.linkedin.com/in/elbruno/) — Professional updates and insights
- 𝕏 **Twitter**: [@elbruno](https://www.x.com/elbruno/) — Quick tips, releases, and tech news

ElBruno.MarkItDotNet

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README