internals

OfficeCLI's Built-In HTML Rendering Engine: Pure C# Open XML Conversion Explained

July 28, 2026 iofficeai/OfficeCLI ↗

OfficeCLI's built-in HTML rendering engine is a lightweight, pure-C# implementation that converts DOCX, PPTX, and XLSX files into static HTML by traversing Open XML packages directly, requiring no external browsers or headless Chromium.

The iOfficeAI/OfficeCLI repository provides a self-contained document conversion pipeline that lives entirely within its source code. Unlike tools that depend on third-party rendering services, this engine parses Office Open XML structures synchronously and emits complete HTML documents suitable for CLI piping, web previews, or programmatic consumption.

How the HTML Rendering Pipeline Works

The engine operates through a five-step pipeline orchestrated by CommandBuilder.RenderViaRegistry and specialized format handlers found in the src/officecli/ directory.

Handler Selection via CommandBuilder.RenderViaRegistry

The entry point for all HTML conversions resides in src/officecli/ResidentServer.cs. Lines 1418-1421 and 1434-1449 implement the RenderViaRegistry logic that inspects file extensions and selects the appropriate backend handler. When the requested backend is html, the system instantiates format-specific handlers—WordHandler, PptHandler, or ExcelHandler—based on whether the input is a DOCX, PPTX, or XLSX file.

Document Traversal and HTML Generation

For Word documents, the WordHandler.HtmlPreview method in src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs (lines 160-183) performs the core conversion. This method walks the document's DOM structure and constructs a complete HTML document, injecting language (lang) and direction (dir) attributes into the root element. It builds valid <head> and <body> sections while preserving document structure and styling metadata from the Open XML.

Paginated Field Resolution

When documents contain page references, the ApplyPageNumFields method (lines 2150-2191 in WordHandler.HtmlPreview.cs) processes <span data-page="…"> and <span data-num-pages="…"> tokens. This replacement occurs during the HTML generation phase, substituting placeholders with actual computed page numbers to maintain pagination accuracy in the static output.

Mathematical Formula Rendering

The engine includes client-side math rendering support. At line 610 of WordHandler.HtmlPreview.cs, the system injects KaTeX script references into the HTML header. This allows LaTeX-style mathematical formulas embedded in Office documents to render correctly in browsers without server-side processing or external dependencies.

Output Delivery

The ResidentServer finalizes the process by writing results to a temporary file (lines 1528-1535) or streaming directly to STDOUT (line 1543). This architecture supports both file-based workflows and Unix-style piped commands, making the result usable from the CLI or any program that consumes the string.

Source Code Architecture

The rendering engine spans several key files in the iOfficeAI/OfficeCLI repository:

Usage Examples

Command Line Interface

Render documents directly from the terminal using the view command with the html backend:


# Convert Word document to HTML and save to file

officecli view report.docx html > report.html

# Stream HTML output to another program

officecli view presentation.pptx html | w3m -T text/html

.NET SDK Integration

Access the rendering engine programmatically through the .NET SDK:

using OfficeCli.Core;
using OfficeCli.Core.Rendering;

// Initialize handler and render to HTML
var html = CommandBuilder.RenderViaRegistry(
    handler: new WordHandler(@"C:\Docs\report.docx"),
    backend: "html",
    options: new RenderOptions());

// html contains complete <html>...</html> string
Console.WriteLine(html);

Python SDK Wrapper

The Python SDK provides simplified access to the same rendering pipeline:

import officecli

# Convert PowerPoint to HTML string

html_content = officecli.render("presentation.pptx", backend="html")
print(html_content)

Summary

  • OfficeCLI's built-in HTML rendering engine is a pure-C# Open XML converter requiring no external dependencies like Chromium or browser engines.

  • Handler-based architecture routes documents through specialized handlers (WordHandler, PptHandler, ExcelHandler) selected by CommandBuilder.RenderViaRegistry in ResidentServer.cs.

  • Synchronous conversion processes documents entirely in-memory, outputting static HTML strings suitable for piping, temporary files, or direct display.

  • Advanced features include automatic page-number field resolution (ApplyPageNumFields) and KaTeX integration for mathematical formula rendering.

Frequently Asked Questions

Does OfficeCLI require Chrome or Chromium to render HTML?

No. OfficeCLI's HTML rendering engine is a completely standalone implementation that parses Open XML packages directly. As implemented in iOfficeAI/OfficeCLI, the conversion occurs entirely within the .NET runtime without spawning external browser processes or relying on headless web technologies.

What file formats does the HTML rendering engine support?

The engine supports DOCX, PPTX, and XLSX files through dedicated handlers found in src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs, src/officecli/Handlers/Ppt/PptHandler.cs, and src/officecli/Handlers/Excel/ExcelHandler.cs respectively. Each handler understands the specific Open XML schema of its format.

How does the engine handle document pagination in HTML?

The ApplyPageNumFields method (lines 2150-2191 in WordHandler.HtmlPreview.cs) scans the generated HTML for <span data-page="…"> and <span data-num-pages="…"> tokens, replacing them with actual computed page numbers during the conversion process to preserve pagination references.

Can I customize the HTML output or inject custom CSS?

While the base implementation in WordHandler.HtmlPreview generates standard HTML with inline styles derived from Open XML formatting, you can post-process the string output returned by CommandBuilder.RenderViaRegistry or pipe the CLI output to transformation tools. The engine returns a complete HTML document string that accepts standard string manipulation.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →