xdoc

Create editable PowerPoint decks. Automate document workflows. Give your AI agent a document runtime.

@s8fy/xdoc brings the native xdoc CLI to npm. Create and edit .pptx files, export PDF and slide images, extract content for an AI workflow, and inspect the result through structured reports. Text, shapes, tables, and supported charts remain native PowerPoint objects you can keep editing.

Build a quarterly review from JSON. Refresh a report from business data. Restyle an existing deck. Let an agent resolve exact objects, preview its changes, and leave a record of how the presentation was produced.

Key features

• Native PowerPoint creation and editing. Work with editable text, shapes, tables, pictures, connectors, equations, and supported charts. Focused edits preserve untouched OOXML; existing SmartArt and complex timing have separate preservation boundaries.
• Charts with real data. Create and update supported classic, 3D, and modern Office charts, including embedded workbook data. Supported 3D scene fields remain native OOXML. Chart kinds, variants, and styling follow the installed schema; authoring and rendering support are separate.
• JSON patches and data-driven reports. Use closed-schema operations, deterministic selectors, recipes, template bindings, loops, conditionals, and macros to assemble or update presentations from supplied content.
• Local PDF and PNG rendering. Export supported text, vectors, images, tables, charts, equations, and effects without PowerPoint, LibreOffice, a browser, or a conversion service. Supply suitable fonts; some effects use raster layers, and PDF/PNG does not play animations.
• Markdown for RAG and AI input. Keep source slide numbers, supported chart data, tables, notes, and packaged image references/assets. AI detail adds element context. OCR, embeddings, indexing, and answer generation belong to the consuming application.
• Reviewable Agent automation. Discover runtime schemas, dry-run before writing, inspect structured errors, and retain revision sidecars. CLI, JSON-RPC, and MCP provide distinct integration surfaces.

Testing and fidelity validation

• 6,000+ automated test cases across the Runtime and related authoring, parsing, PDF/PNG, Markdown, math, and metafile engines help detect regressions.
• Tested on 500+ real presentation decks, alongside focused fixtures, to evaluate real-document behavior and rendering.
• A proprietary fidelity workflow developed in-house supports ongoing rendering improvements and regression prevention.

Explore the product overview, quickstart, and Agent protocol guide.

Install and try it

Requires Node.js 22 or newer. See supported platforms.

npm install --global @s8fy/xdoc
xdoc --version

Start with an existing presentation and generate a review bundle in one command:

# Export PDF, slide PNGs, a contact sheet, and AI-ready Markdown
xdoc convert deck.pptx --to pdf,png,md --md-detail ai --contact-sheet --output-dir exports

Conversion and native PPTX editing run locally without requiring an Office installation. Rendering uses xdoc's own backends; available fonts affect the result. Free mode has task limits and visual watermarks.

What you can do

Create your first deck from JSON

Save this as review.patch.json. It creates a title slide and a KPI slide using built-in recipes:

{
  "schemaVersion": "pptx-patch/v1",
  "ops": [
    {
      "op": "add-slide",
      "recipe": {
        "kind": "title",
        "title": "Quarterly momentum",
        "subtitle": "A business review built with xdoc"
      }
    },
    {
      "op": "add-slide",
      "recipe": {
        "kind": "kpi-grid",
        "title": "Growth at a glance",
        "items": [
          { "label": "Revenue", "value": "$2.4M", "delta": "+18%" },
          { "label": "Customers", "value": "1,280", "delta": "+22%" },
          { "label": "Retention", "value": "98%", "delta": "+2 pts" }
        ]
      }
    }
  ]
}

Validate the plan, create the deck, and render a preview:

# Resolve and simulate the patch without writing the presentation
xdoc pptx apply --patch review.patch.json --output review.pptx --dry-run --json

# Create review.pptx and its review.pptx.xdoc.json sidecar
xdoc pptx apply --patch review.patch.json --output review.pptx --json

# Render PNGs and a contact sheet
xdoc pptx preview review.pptx --output-dir review-previews --contact-sheet --json

Open review.pptx in PowerPoint and edit the generated text and shapes. Change the KPI values in JSON to generate another review, or explore recipes such as timeline, roadmap, process-flow, comparison-table, and gantt. Compose individual operations to add charts, tables, diagrams, and supported animations or transitions. Patch slide indexes start at 0, while CLI --slides selections start at 1.

Existing output paths are protected by default. Add --overwrite when you intend to replace a previous output.

Turn everyday deck work into commands

Inspect, target, and edit

Find the actual PowerPoint objects before constructing an edit patch:

xdoc pptx inspect deck.pptx --json
xdoc pptx select deck.pptx --query '{"textRegex":"Revenue"}' --json

# edit.patch.json contains your schema-valid changes to the selected objects
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --dry-run --json
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --json

Inspect supplies object identity, text, geometry, layouts, and styles. Selectors resolve targets deterministically; ambiguous matches produce an error with candidates. Patch operations are adopted only after the full operation set succeeds. The commands above write a separate candidate for review.

Fill a template or try a new look

Use your own template.pptx, business data in data.json, and schema-defined text/table/chart mappings in bindings.json:

xdoc pptx template-fill data.json --template template.pptx --bindings bindings.json --output report.pptx

Discover built-in theme packs, then try one on a deck:

xdoc pptx catalog themes --json
xdoc pptx swap-theme deck.pptx --theme corporate-blue --output themed.pptx
xdoc pptx swap-style deck.pptx --style consulting --output styled.pptx

Extract source material and convert batches

# Extract the outline, resource inventory, notes, links, and fonts
xdoc extract deck.pptx --parts map,resources,notes,links,fonts --pretty --output artifacts.json

# Read text from a PDF and normalize a local HTML page to Markdown
xdoc pdf extract-text source.pdf --json --pretty
xdoc html2md page.html --output page.md

# Convert a directory and retain a structured batch summary
xdoc convert ./decks --recursive --to pdf --output-dir ./converted --report batch.json

PDF text and HTML Markdown can feed a brief or an agent's content pipeline. Creating the presentation then uses recipes, patches, or a PPTX template.

Check the result and retain the evidence

# Include accessibility alongside the standard preflight checks
xdoc check updated.pptx --checks all --output preflight.json

# Check static layout risks and compare the source with the candidate
xdoc pptx vision-check updated.pptx --json
xdoc pptx diff deck.pptx updated.pptx --json

# Review the actual rendered slides
xdoc pptx preview updated.pptx --output-dir updated-previews --contact-sheet --json

# Inspect the revision record or replay its patch
xdoc pptx audit --from-sidecar updated.pptx.xdoc.json --json
xdoc pptx replay --from-sidecar updated.pptx.xdoc.json --output replayed.pptx

The default .xdoc.json sidecar records the materialized patch, runtime identity, and apply report. Keep the source deck too: replay of an existing-deck edit requires the recorded input to remain available. Sidecars contain revision evidence; fresh checks and previews validate the current presentation.

Built for AI agents

xdoc exposes its own operations, field contracts, examples, catalogs, feature support, and report formats. An agent can discover the installed runtime, inspect a deck, construct a patch, dry-run it, apply it, and verify the result using machine-readable data at each step. Your agent supplies the content, translations, and design decisions; xdoc executes the document work.

# Discover patch operations, then ask for the exact fields you need
xdoc schema --mode index
xdoc schema --mode ops --ops add-chart,set-chart-data --minimal

# Explore built-in examples and the complete runtime contract
xdoc schema --mode examples
xdoc schema > runtime-schema.json

# Browse native PowerPoint shapes
xdoc pptx catalog shapes --json

The 0.12.2 runtime exposes 58 patch operations, 18 slide recipe kinds, 182 preset shapes, 9 theme packs, and 4 style packs. Chart types and advanced features carry individual support statuses. Use the installed schema to choose supported operations and read the scope of partial or preserve-only features.

Choose the process interface that fits your host:

For an MCP client that accepts mcpServers configuration:

{
  "mcpServers": {
    "xdoc": {
      "command": "xdoc",
      "args": ["mcp"]
    }
  }
}

The MCP adapter exposes xdoc_schema, pptx_inspect, and pptx_apply. Conversion, previews, and other checks use the CLI. For repeatable integrations, pin the npm version and capture that executable's schema. This package exposes the xdoc command; process arguments, stdio protocols, and JSON reports form the public integration boundary.

Supported platforms

npm selects an exact-version platform package containing the native executable and bundled PDFium backend. Install scripts do not download binaries from an external release server. Unsupported operating systems, architectures, or macOS versions receive an actionable error.

Scope and compatibility

• Current inputs: PPTX, PDF, and HTML, plus JSON patches, recipes, and data bindings for PPTX authoring. DOCX and XLSX conversion remain reserved.
• Editing and preservation: ordinary PowerPoint objects have native edit paths. Complex animation, SmartArt, and other advanced features have their own supported, partial, preserve-only, or unsupported status.
• Rendering and review: font availability and the selected feature affect output. Static checks, rendered previews, and target-Office compatibility reports answer different questions; review the rendered result for delivery.

Free mode and licensing

Free mode provides all core features for single-user local use, with up to 10 slides per task and 5 MiB of compressed PPTX inputs combined. Visual outputs, including editable PPTX, PDF, and PNG, carry a structurify.io watermark. No account or license credential is required to start; tasks exceeding the Free limits are denied.

Personal and Enterprise licenses are offline entitlements that remove the plan-level slide/PPTX byte limits and new plan watermarks. Local scripts and a per-user daemon are included in the launch plans; CI, shared servers, and Service/API use are outside those plans.

The public packages use the PolyForm Noncommercial License 1.0.0 unless separately licensed. Runtime access and legal usage rights are separate; commercial use requires the applicable separate terms. Platform packages also retain the bundled PDFium third-party license notices.

Support and package maintenance

Report installation, platform selection, and launcher issues in the hustcer/xdoc-feedback issue tracker. For native runtime behavior, use the upstream support channel supplied with your xdoc distribution or license.

This directory maintains npm packaging and release automation. Native release assets are pinned to reviewed SHA-256 digests in release-lock.json. See the maintainer release process.