Preface

Recently, while working on tender documents, I realized that some documents are very text-heavy. Having a large model fully interpret them isn't very practical. Setting aside whether the context length is sufficient, the token consumption alone would be off the charts.

So, I thought of a clever workaround: extracting the PDF's table of contents for analysis. I got right to it and wrote a tool in C# to implement the table of contents extraction. The results turned out quite well.

Later, I continued refining this tool, adding features like semantic recognition.

I continued using the C# + AOT + GitHub Actions + dotnet tool + nuget workflow for development.

Project address: https://github.com/star-plan/pdf-toc-extractor

Similar projects:

• SharpIco
• ImageGlider

Why Directory Extraction?

There are so many tools for converting PDFs to Word, Markdown, and other formats.

We're not competing in that space.

(I mean, I actually built one recently 🤣, and I might integrate PDF-to-document conversion into this project later.)

Instead, we're focusing on this niche need—doing a great job at extracting PDF directories.

Later on, we added semantic recognition features. Some PDFs don't have an embedded directory, so it's necessary to analyze and extract a directory from the content itself.

Initially, I tried using pattern matching, but the results were terrible. I then switched to an NLP approach—although I only used the simplest form of semantic recognition, the improvement was significant!

It really shows how important it is to choose the right tool.

PdfTocExtractor

PdfTocExtractor is a lightweight PDF Table of Contents (TOC) extraction tool implemented in pure C# AOT. It is used to extract the table of contents from PDF files and export it to various formats. It supports Markdown, JSON, XML, plain text, and other formats. Completely free from command-line dependencies and requiring no additional PDF processing tools, it is ideal for embedding, distributing, or integrating into automation workflows within .NET projects.

With PdfTocExtractor, you can easily extract bookmarks and the table of contents structure from PDF documents to generate clear navigation documents. The newly added semantic analysis feature in v2.0 allows you to automatically identify chapter titles using NLP-based intelligent analysis, even when the PDF lacks embedded bookmarks. This makes it perfect for document processing, content analysis, and workflow automation.

🚀 Cross-platform, zero dependencies, lightning-fast extraction—everything you need is in PdfTocExtractor!

✨ Features

• 📖 Extract bookmark/table of contents information from PDF files
• 🧠 Semantic analysis capability: NLP-based intelligent chapter title recognition, suitable for bookmark-less PDFs
• 📄 Supports multiple output formats: Markdown, JSON, XML, plain text
• 🎯 Configurable export options (hierarchy depth, page number format, etc.)
• 🔧 Extensible exporter architecture, supports custom formats
• ⚡ Asynchronous operation support, high-performance processing
• 🛠️ Provides command-line tools and NuGet package
• 🚀 Supports AOT compilation, native performance without .NET runtime
• 🌐 Cross-platform support: Windows, Linux, macOS
• 🎛️ Multiple analysis modes: default, strict, and lenient modes available

📄 Supported Output Formats

• Markdown (md, markdown) - Suitable for documents and web display, supports hierarchical structure
• JSON (json) - Ideal for program processing and API integration, contains complete metadata
• XML (xml) - Structured data exchange, standardized format
• Text (txt, text) - Plain text format, concise and readable

Usage

Same as other tools

It provides both a NuGet library and a dotnet tool command-line interface

You can use it by importing it as a library or use it directly in the command line

Command Line

Install the CLI Tool

dotnet tool install --global PdfTocExtractor.Cli

Command Line Usage

# 🌟 Smart Extraction (Recommended) - Automatically selects the best method
pdftoc smart document.pdf -o output.md
# 📖 Extract PDF Bookmarks (Traditional Method)
pdftoc extract document.pdf -o output.md
# 🧠 Semantic Analysis (v2.0 New Feature - For PDFs without Bookmarks)
pdftoc semantic document.pdf -o output.md
# Specify Output Format
```markdown
pdftoc smart document.pdf -o output.json -f json

Set Maximum Hierarchy Depth

pdftoc smart document.pdf -o output.xml --max-depth 3

Custom Title and Page Number Format

pdftoc smart document.pdf -o output.txt --title "My Document Table of Contents" --page-format "Page {0}"

Semantic Analysis - Strict Mode (More Precise Title Recognition)

pdftoc semantic document.pdf -o output.md --mode strict --confidence 0.7

Semantic Analysis - Debug Mode (View Analysis Process)

pdftoc semantic document.pdf -o output.md --debug --verbose

Structure Analysis - Loose Mode (Recognizing More Potential Headings)

pdftoc analyze document.pdf -o output.md --relaxed

Structure Analysis - Custom Parameters

pdftoc analyze document.pdf -o output.md --min-font-size 14 --use-bold --debug

Intelligent Extraction: with Structure Analysis Configuration

pdftoc smart document.pdf -o output.md --analysis-preset strict --debug-analysis

Show Detailed Output

pdftoc smart document.pdf -o output.md --verbose

Diagnosing PDF File Issues

pdftoc diagnose document.pdf

### Using as a Library

Install the core library

```bash
dotnet add package PdfTocExtractor

Code Example

using PdfTocExtractor;
using PdfTocExtractor.Exporters;
using PdfTocExtractor.Models;

// Create an extractor instance
var extractor = new PdfTocExtractor();

// 🌟 Smart extraction (recommended) - automatically selects the best method
var tocItems = await extractor.ExtractTocSmartAsync("document.pdf");

// 📖 Traditional method: Extract PDF bookmarks
var bookmarkItems = await extractor.ExtractTocAsync("document.pdf");

// 🧠 Structure analysis: Suitable for PDFs without bookmarks
var structureItems = await extractor.AnalyzeStructureAsync("document.pdf");

// 🧠 Structure analysis: Using custom configuration
var analysisOptions = new StructureAnalysisOptions
{
    MinFontSizeForHeading = 14f,
    UseBoldAsIndicator = true,
    MaxHeadingLevels = 4,
    RequireStandaloneHeadings = true,
    DebugMode = false
};
var customStructureItems = await extractor.AnalyzeStructureAsync("document.pdf", analysisOptions);

// 🧠 Using preset configurations
var strictItems = await extractor.AnalyzeStructureAsync("document.pdf", StructureAnalysisOptions.Strict);
var relaxedItems = await extractor.AnalyzeStructureAsync("document.pdf", StructureAnalysisOptions.Relaxed);

// Export to Markdown
await extractor.ExportToFileAsync(tocItems, "output.md", "markdown");

// Export to JSON (with custom options)
var exportOptions = new ExportOptions
{
    MaxDepth = 3,
    IncludePageNumbers = true,
    CustomTitle = "Document Table of Contents"
};
await extractor.ExportToFileAsync(tocItems, "output.json", "json", exportOptions);

// Smart extraction and direct export
await extractor.ExtractSmartAndExportAsync("document.pdf", "output.xml",
    exportOptions: exportOptions,
    structureOptions: StructureAnalysisOptions.Default);

Extensibility

Custom exporters can be created by implementing the IExporter interface:

public class CustomExporter : IExporter
{
    public string FormatName => "Custom";
    public string FileExtension => "custom";

    public string Export(IEnumerable<TocItem> tocItems, ExportOptions? options = null)
    {
        // 实现自定义导出逻辑
        return "custom format content";
    }

    public async Task ExportToFileAsync(IEnumerable<TocItem> tocItems, string filePath, ExportOptions? options = null)
    {
        var content = Export(tocItems, options);
        await File.WriteAllTextAsync(filePath, content);
    }
}

// 注册自定义导出器
extractor.RegisterExporter("custom", new CustomExporter());

Technical Implementation

PdfTocExtractor uses the following technologies:

• .NET 9.0 - Modern .NET platform
• iText 9.2.0 - Powerful PDF processing library
• iText7.bouncy-castle-adapter 9.2.0 - Encrypted PDF support (required)
• Newtonsoft.Json 13.0.3 - JSON serialization
• System.CommandLine 2.0.0 - Command-line argument parsing
• Ahead-of-Time (AOT) compilation support - Native performance without the .NET runtime

TODO Plan

AI-Enhanced Features

• AI Table of Contents (TOC) Recognition - Using machine learning technology to identify the table of contents structure of PDF documents without bookmarks/outline data
  • Integrating OCR technology to recognize table of contents pages in scanned PDFs
  • Intelligent TOC extraction based on text analysis and format recognition
  • Support for multi-language TOC recognition (Chinese, English, Japanese, etc.)
  • Intelligent inference of TOC hierarchy
  • Automatic matching algorithm between page numbers and TOC entries

Web Service Interfaces

• RESTful API Development - Provide HTTP-based Web API services
  • PDF File Upload Interface
  • Table of Contents Extraction API Endpoint
  • Multi-format Export API (JSON, XML, Markdown, etc.)
  • Batch Processing Interface
  • Task Status Query Interface
  • API Documentation and Swagger Integration

Web Frontend Interface

• Modern Web UI - Develop a user-friendly web frontend interface
  • Drag-and-drop PDF file upload
  • Real-time table of contents extraction progress display
  • Table of contents structure visual preview
  • Multi-format export options interface
  • History and file management
  • Responsive design, supports mobile device access

Technical Architecture Optimization

• Microservices Architecture - Modularize functional modules into independent microservices
  • PDF Processing Service
  • AI Recognition Service
  • File Storage Service
  • User Management Service
  • Containerized Deployment Support (Docker)

Advanced Features

• Intelligent Analysis - Provides more document analysis features
  • Document Structure Analysis and Statistics
  • Table of Contents Quality Assessment
  • Duplicate Content Detection
  • Document Similarity Comparison
  • Batch Document Processing and Analysis Reports

Enterprise Features

• Security and Permissions - Enterprise-level security features
  • User authentication and authorization
  • File access control
  • Audit logging
  • Encrypted data storage
  • API access restrictions and quota management

Summary

Here, the core capabilities of PdfTocExtractor have been fully unveiled: whether your PDF has bookmarks or not, you can generate a structured table of contents with a single click; whether you prefer command-line batch processing or flexible integration in code, it handles it all effortlessly. ⚡️

In real-world projects, this tool has saved me a tremendous amount of time manually organizing tables of contents, and it also avoids tedious issues like OCR misrecognition and format chaos. The new Smart and Semantic dual-engine is particularly impressive—both fast and accurate, truly awesome! 😋

Of course, the project is far from "finished." Future plans like AI directory recognition, a Web API, a modern UI, and even an enterprise permission system are all on the roadmap, waiting to be implemented step by step. If you're also interested in these directions, feel free to open an issue / submit a PR / give a Star, and let's work together to make it the best PDF table of contents tool! 🌟

Lastly, if this article has been helpful to you, don't forget to give the repository a Star so more people can benefit; you're also welcome to share your user experience or suggest features in the comments. See you in the next article～👋