how-to-guide

How to Use OfficeCLI HTML Rendering Engine for Document Previews

August 6, 2026 iofficeai/OfficeCLI ↗

OfficeCLI's built-in HTML rendering engine converts DOCX, PPTX, and XLSX files into self-contained, browser-ready HTML snapshots via the view command with html mode.

The rendering engine produces a single HTML file with all assets inlined, making it ideal for CI artifacts, agent workflows, and quick visual validation without external dependencies. For DOCX files, the engine assembles a complete document starting with <!DOCTYPE html> through the closing </html> tag in WordHandler.HtmlPreview.cs (lines 160‑1398). The same renderer powers the live watch command, ensuring identical output between one-shot previews and streaming updates.

Activating the HTML Rendering Mode

The HTML preview workflow begins in CommandBuilder.View.cs. When you invoke view html, the CLI validates the --render flag, instantiates a fresh RenderOptions object, and calls RenderViaRegistry to route the request to the appropriate format handler.


# Basic usage – outputs absolute path to temporary HTML file

officecli view report.docx html

The handler receives the RenderOptions instance and returns a fully inlined HTML document. The CLI writes this to a temporary file and prints the path to stdout for immediate browser opening or scripting.

Supported File Types and Handlers

OfficeCLI routes HTML rendering through format-specific handlers based on file extension:

Extension	Handler	Source File
.docx	`WordHandler.HtmlPreview`	`src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs`
.pptx	`PptHandler`	Referenced via `RenderViaRegistry`
.xlsx	`ExcelHandler`	Referenced via `RenderViaRegistry`

Each handler produces identical output structure: a standalone HTML file with embedded CSS, fonts, and images. The ResidentServer.cs file reuses this same pipeline for incremental preview updates during watch sessions.

Controlling Output Location and Scope

The view html command accepts several flags to customize the generated preview:


# Save to specific path instead of temporary file

officecli view deck.pptx html -o /artifacts/deck-preview.html

# Render specific page from Word document

officecli view contract.docx html --page 3

# Limit spreadsheet preview to sheets 1-2

officecli view budget.xlsx html --start 1 --end 2

In CommandBuilder.View.cs (lines 143‑151), the --page, --start, and --end parameters populate the RenderOptions object before the registry dispatch.

Integration with Live Preview and Automation

The HTML engine serves dual purposes. According to ResidentServer.cs, the same RenderViaRegistry call with fresh RenderOptions handles both:

One-shot previews: view html for static output
Streaming updates: watch command for live editing feedback

This design guarantees that agents and CI pipelines receive visually identical results. The README confirms that output is "standalone HTML file, assets inlined. Open in any browser." The SKILL guide recommends view html for automated QA pipelines and visual regression testing.

File Structure and Implementation Details

Understanding the source layout helps when extending or debugging the renderer:

src/officecli/CommandBuilder.View.cs: Entry point, argument parsing, RenderOptions construction
src/officecli/ResidentServer.cs: Orchestrates watch mode with same HTML pipeline
src/officecli/Handlers/Word/WordHandler.HtmlPreview.cs: DOCX-specific HTML generation with full document structure

The WordHandler.HtmlPreview.cs implementation demonstrates the engine's thoroughness: it constructs valid HTML5 from DOCTYPE declaration through final closing tag, handling complex document elements including tables, footnotes, and embedded media.

Summary

Primary command: officecli view <file> html triggers the rendering engine
Output: Self-contained HTML with inlined assets, written to temp file or specified path
Implementation: CommandBuilder.View.cs builds RenderOptions, RenderViaRegistry dispatches to format handlers
Consistency: Same engine powers view and watch commands
Customization: --page, --start, --end, and -o flags control scope and destination

Frequently Asked Questions

Can I use the HTML renderer without installing a browser?

Yes. The engine generates standard HTML5; any environment can save, archive, or serve the output. The file prints to stdout as an absolute path for headless workflows.

Does the HTML output require internet access to render?

No. According to the source implementation in WordHandler.HtmlPreview.cs, all CSS, fonts, and images are base64-inlined. The resulting file opens correctly in air-gapped environments.

How does `view html` differ from `watch` mode?

The view command produces a single snapshot and exits. The watch command uses ResidentServer.cs to call the identical renderer repeatedly on file changes, streaming updated HTML paths to connected clients.

Which Office formats support page and sheet limiting?

The --page flag applies to DOCX files. The --start and --end flags apply to XLSX files for sheet range selection. PPTX files currently render complete decks; per-slide selection requires post-processing the output.

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"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how iofficeai/OfficeCLI works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

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