document-svg

Preview documents and technical drawings as SVG pages in your application.

A Rust library and CLI with Node.js and Python bindings. Convert PDF, PowerPoint, Excel, Word and draw.io files into one SVG per page, display them in a browser, and inspect conversion warnings before sharing the result.

日本語 · 简体中文预览指南 · Examples · Releases

Project site (English / 日本語 / 中文) — use cases, the full format map, and a live sample gallery

Available on npm for Node.js, PyPI for Python, and crates.io for Rust and the docsvg CLI.

What you can do

Supported inputs include PDF/FDF/XFDF form data (.fdf, .xfdf), legacy Word Binary .doc/.dot, text-only legacy PowerPoint Binary .ppt, Microsoft Project XML (.xml with the Project namespace; .mspdi alias), generic XML (.xml fallback), legacy Excel .xls and binary Excel .xlsb, legacy Visio Binary .vsd/.vss/.vst/.vsw, Autodesk DWG (.dwg) and Rhino/OpenNURBS 3DM (.3dm), Microsoft Access (.accdb, .accde, .mdb, .mde), Dassault 3DXML (.3dxml), Apple iWork Pages/Numbers/Keynote (.pages, .numbers, .key), SYLK spreadsheets .slk and DIF interchange tables .dif, Office Open XML Transitional/Strict and Flat OPC single-XML packages (.flatopc, .fopc, .flatopc.xml) (including Visio .vsdx, .vsdm, .vstx, .vstm and legacy XML .vdx), Apple iWork packages (.pages, .numbers, .key), Autodesk DWG (.dwg) and Rhino/OpenNURBS 3DM (.3dm), Microsoft Access (.accdb, .accde, .mdb, .mde), Dassault 3DXML (.3dxml), RTF, iCalendar .ics/vCalendar .vcs, vCard contact files .vcf, MIME e-mail .eml, Apple Mail messages .emlx, Outlook .msg and mailbox archives .mbox, MHTML web archives (.mht, .mhtml), XPS/OpenXPS/DWFx (.xps, .oxps, .dwfx), OpenDocument Text, spreadsheets, presentations, and drawings (.odt, .ott, .fodt, .sxw, .stw, .sxg, .ods, .ots, .fods, .sxc, .stc, .odp, .otp, .fodp, .sxi, .sti, .odg, .otg, .fodg, .sxd, .std), HTML, DocBook (.dbk, .docbook), DITA topics/maps (.dita, .ditamap), HWPX (.hwpx), XMind (.xmind), NIfTI (.nii, .nii.gz), FITS (.fits, .fit, .fts, .fits.gz), MRC (.mrc, .map, .mrc.gz), SQLite (.sqlite, .sqlite3, .db), mmCIF/PDBx (.cif, .mmcif), Tripos MOL2 (.mol2), RDF Turtle/N-Triples (.ttl, .nt, .nq), EPS/PostScript (.eps, .ps), EPUB, FictionBook 2 (.fb2, .fb2.zip), PalmDOC/MOBI (.mobi, .prc), JATS article XML (.jats, .nxml), TEI P5 scholarly XML (.tei, .tei.xml), ALTO OCR/layout XML (.alto, .alto.xml), METS archive XML (.mets, .mets.xml), MARCXML (.marcxml, .marc.xml), MARC21 ISO 2709 (.marc, .iso2709), MODS XML (.mods, .mods.xml), CBZ comic archives, SubRip/WebVTT/TTML subtitles, Jupyter notebooks (.ipynb), Quarto/R Markdown (.qmd, .Rmd, .rmarkdown), Markdown and plain text, AsciiDoc, reStructuredText (.rst, .rest), Org-mode (.org), XLIFF localization files (.xlf, .xliff), GNU gettext translation catalogs (.po, .pot), BibTeX bibliographies (.bib, .bibtex), PDB coordinate models (.pdb, .ent), FASTA/FASTQ, GFF3/GTF, BED/BEDGraph, VCF, SAM, WIG, MAF, Newick, Stockholm, CLUSTAL and NEXUS bioinformatics files (.fa, .fastq, .gff3, .bed, .vcf, .sam, .wig, .maf, .nwk, .sto, .aln, .nex), GenBank flat files (.gb, .gbk, .genbank), EMBL-Bank flat files (.embl, .emb), UniProtKB/Swiss-Prot protein flat files (.dat, .uniprot, .swissprot), RIS bibliography (.ris), SPICE/ngspice netlists (.cir, .sp, .spice, .ckt, .net), KiCad legacy Eeschema schematics (.sch), KiCad 6+ S-expression schematics (.kicad_sch), LTspice schematics (.asc with Version signature), Autodesk EAGLE XML schematics (.sch with eagle signature), V2000 and core V3000 MOL/SDF chemical structures plus V2000 RXN reactions (.mol, .sdf, .sd, .rxn), diagrams (draw.io, GraphML (.graphml), GEXF (.gexf), XGMML (.xgmml), Graph Modeling Language (.gml), BPMN 2.0, CMMN 1.1, DMN 1.5, ReqIF 1.0.1/1.2, XMI 2.1–2.5, DOT, Mermaid, PlantUML, D2, Excalidraw), tables and graphics (OpenAPI/Swagger (.openapi.json, .swagger.json, .openapi.yaml, .swagger.yaml), AsyncAPI (.asyncapi.json, .asyncapi.yaml, .asyncapi.yml), JSON Schema (.schema.json, .jsonschema, .schema.yaml, .schema.yml), HAR (.har), WARC (.warc, .warc.gz), WACZ (.wacz), Postman Collection v2.1 (.postman_collection.json), GraphQL SDL (.graphql, .graphqls, .gql), Protocol Buffers (.proto), Kubernetes (.k8s.yaml, .k8s.yml, .kubernetes.yaml, .kube.yaml), Docker Compose (compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml), GitHub Actions workflows (.github/workflows/*.yaml, .github/workflows/*.yml), JUnit XML reports (junit.xml, test-results.xml, TEST-*.xml), SARIF 2.1.0 reports (.sarif, .sarif.json), Terraform JSON plans (tfplan.json, .tfplan.json), CycloneDX BOMs (bom.json, bom.xml, *.cdx.json, *.cdx.xml), SPDX JSON/tag:value (spdx.json, sbom.spdx.json, *.spdx.json, .spdx, .spdx.txt), JaCoCo/Cobertura coverage XML (jacoco.xml, cobertura.xml, coverage.xml), LCOV tracefiles (.info, lcov.info, coverage.info), JSON Patch (.jsonpatch, .json-patch, .patch.json), JSON Merge Patch (.mergepatch, .json-merge-patch, .merge-patch.json), CSL-JSON (.csl.json, .csl-json, .cite.json), JSON Feed (.jsonfeed, .json-feed, .feed.json) and CloudEvents JSON (.cloudevent.json, .cloud-event.json, .cloudevents.json, .ce.json, .cloudevent, .cloudevents) and FHIR JSON (.fhir.json, .fhirjson, .fhir, .bundle.fhir.json, .fhir-bundle.json) and Avro JSON schemas (.avsc, .avpr, .avro.json, .avro-schema.json) and OTLP JSON (.otlp.json, .otlp.trace.json, .otlp.metrics.json, .otlp.logs.json) and OCEL JSON (.jsonocel, .ocel.json, .ocel-json) and JSON:API (.jsonapi, .json-api.json, .jsonapi.json), NetCDF classic (.nc, .nc3, .cdf), HDF5/CGNS (.h5, .hdf5, .hdf, .h5part, .cgns) and Exodus II (.e, .exo, .ex2, .ex2m, .exii), ARFF (.arff), JSON-LD (.jsonld, .json-ld), CSV/TSV, generic JSON (.json), TOML configuration (.toml), YAML 1.2 configuration (.yaml, .yml), Java Properties (.properties), RFC 7464 JSON Text Sequences (.jsons, .jsonseq, .jsonl), GeoJSON, RFC 8142 GeoJSON Text Sequences (.geojsons, .geojsonl), TopoJSON (.topojson), GeoRSS, GPX, GML, KML/KMZ, ESRI ASCII Grid rasters (.asc), dBASE III/III+ attribute tables (.dbf), GeoPackage vector and raster-tile maps (.gpkg), ESRI Shapefile map data (.geojson, .rss, .atom, .georss, .gpx, .gml, .kml, .kmz, .shp), WKT/EWKT geometry (.wkt, .ewkt), chart JSON, LaTeX math, QR, raster PNG/JPEG/BMP/GIF/WebP, Netpbm PBM/PGM/PPM/PAM (.pbm, .pgm, .ppm, .pnm, .pam), and standalone JPEG 2000 (.jp2, .j2k, .j2c, .jpc, .jpx) images including multi-page TIFF), SVG/SVGZ, and technical formats (OpenSCAD .scad, AMF .amf, PLMXML .plmxml/.plm.xml, STEP-XML .stepxml/.stpx, QIF .qif/.qif.xml, TMX .tmx/.tmx.xml, TBX .tbx/.tbx.xml, gbXML .gbxml/.gbxml.xml, FHIR XML .fhir.xml/.fhirxml, Adobe IDML .idml, XPDL .xpdl/.xpdl.xml, ONIX .onix/.onix.xml, OAI-PMH .oaipmh/.oai.xml, CDA .cda/.cda.xml, ISO 20022 .iso20022.xml/.pain.xml/.pacs.xml/.camt.xml, SBML .sbml, CellML .cellml, OCEL XML .xmlocel, EnergyPlus IDF .idf, EnergyPlus EPW .epw, RINEX .rnx/.obs/.nav, ACIS SAT .sat, SED-ML .sedml, SBGN-ML .sbgnml, COMBINE/OMEX .omex, XDMF .xdmf, VTK PVD .pvd, FDS .fds, AbiWord .abw, NeuroML .nml, BioPAX .biopax, XML Schema .xsd, XSLT .xsl/.xslt, XSL-FO .fo/.xslfo, ANSYS CDB .cdb, Abaqus .inp, LS-DYNA Keyword .k/.key, Nastran Bulk Data .bdf/.nas, UNV/UFF .unv, MEDIT .mesh/.meshb, SU2 CFD meshes .su2, OpenFOAM polyMesh cases .foam, ASAM OpenDRIVE road networks .xodr, ASAM OpenSCENARIO scenarios .xosc, Tecplot ASCII CAE meshes .dat/.tec, EnSight Gold ASCII cases .case/.geo, PLOT3D ASCII structured grids .p3d/.plot3d/.p3, VRML97 meshes .wrl/.vrml, OFF polygon meshes .off, IFC4 BIM Industry Foundation Classes .ifc/.ifcxml/.ifczip, buildingSMART BCFZIP issue packages .bcfzip, PCL point clouds .pcd, ASCII XYZ point clouds .xyz, ASTM E57 point clouds .e57, Leica PTS/PTX point clouds .pts/.ptx, ASPRS LAS/LAZ point clouds .las/.laz, KiCad PCB boards .kicad_pcb, DXF, Gerber, HP-GL, G-code, Excellon, STL, 3MF, glTF .gltf/.glb, COLLADA .dae, X3D .x3d, STEP, IGES, OBJ, PLY, Gmsh, VTK Legacy/XML .vtk/.vtu/.vtp/.vti/.vtr/.vts). See the format matrix below for extensions and fidelity notes.

DICOM Part 10 image files (.dcm, .dicom) render as PNG-backed SVG pages; DICOM Structured Reports are recognized by their SR SOP Class and rendered as bounded content tables; multiframe objects produce one page per frame. JPEG 2000 Part 1 lossless and general transfer syntaxes are decoded after checking each codestream's declared dimensions, component count, and sample precision against the bounded DICOM attributes. The media directory file DICOMDIR (or .dicomdir) follows Directory Record offsets and resolves referenced image File IDs inside the directory tree; each referenced frame becomes a page. Encapsulated PDF Storage objects are recognized by SOP Class and application/pdf MIME type; the bounded embedded stream goes through the same PDF renderer. DICOM patient/study attributes are not copied, but content already in the PDF remains, so this does not de-identify the report.

Reverse export supports PPTX, DOCX, XLSX, draw.io, CAD/CAM/3D (DXF, G-code, Gerber, HP-GL, Excellon, STL, 3MF, OBJ, PLY, STEP, IGES), Gmsh/VTK, DOT/Mermaid, Markdown/CSV, LaTeX, React/Vue/Svelte, HTML, WebP, SVG path data, PNG, and Data URI.

Supported format matrix

Conversions are classified into three fidelity tiers:

• A (Deterministic): 1:1 syntax mapping, exact geometric projection, or lossless metadata round-tripping.
• B (Vectorization): Raster image processing and contour tracing from pixel data.
• C (Heuristic Reconstruction): Structural inference from unannotated 2D geometries (e.g., cell clustering for tables, topological parsing for graphs).

The native Node.js API can run conversion in a server or Electron main process. For a static, frontend-only application, the separate WebAssembly package supports PDF, DOCX, XLSX, and PPTX entirely in the browser. It converts each page to SVG in a Web Worker and does not use pdf.js or upload the document. Build instructions and a static viewer example are in bindings/wasm/README.md.

Install

Choose one installation method for your use case; you do not need all three. Use npm to call the converter from a Node.js/TypeScript application, pip to call it from Python, or Cargo to install the standalone docsvg command. The npm and pip packages are language bindings, not installations of the CLI.

Python: install with pip

Create and activate a virtual environment, then install the Python package:

python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows PowerShell instead: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install document-svg
python -c "from document_svg import convert; print('Ready')"

The package name is document-svg (hyphen); the Python import is document_svg (underscore). If your system uses python3, substitute it for python. See the Python example below.

JavaScript / TypeScript: install with npm

Run this in your application's directory:

npm install document-svg
node -e "require('document-svg'); console.log('Ready')"

TypeScript declarations are included; no separate @types package is needed. Keep npm optional dependencies enabled: they supply the native binary for your platform. Run conversion in Node.js, not directly in a browser. See the Node.js example below.

Standalone command: install with Cargo

cargo install document-svg --locked
docsvg --version
docsvg report.pdf --output output/report

For use as a Rust library instead, run cargo add document-svg in your Rust project. For a compiler-free CLI installation, download the archive matching your operating system and CPU from GitHub Releases, extract it, and put docsvg (or docsvg.exe) on your PATH.

Platform support and troubleshooting

Python wheels use the stable CPython ABI for GIL-enabled Python. Matching prebuilt packages do not require a Rust compiler. Alpine Python users need a Rust toolchain and native build tools to install the source distribution. Prebuilt musllinux Python wheels are not included in this release because their additional bundled compiler runtime has not passed the release license review.

If pip attempts a source build, a matching wheel may not be available for your Python/platform combination; update pip and check the release assets first. Source builds require Rust and a native linker. If npm cannot load the native binding, check that optional dependencies were installed and that your Node.js architecture matches the machine. Do not copy node_modules between platforms.

For a prebuilt CLI or source archives, see GitHub Releases. For authenticated GitHub Packages distribution, see Publishing and releases. The public npm registry is the simplest choice for most JavaScript users.

Build from source

git clone https://github.com/ryusui-hiro/document-svg.git
cd document-svg
cargo install --path . --locked

The Rust crate requires Rust 1.88 or newer. Release builds are tested with Rust 1.93.

Quick start

CLI

docsvg samples/source/sample.pptx --output output/slides
docsvg report.pdf --output output/report --max-pages 100
docsvg architecture.drawio --output output/diagram
docsvg aws.drawio --output output/aws --stencils path/to/drawio/stencils

# Optimize or clean an existing SVG
docsvg transform input.svg --output output.svg --minify --remove-metadata --clean-paths --strip-empty-groups

--stencils takes draw.io's own stencil files, or your own in the same format; the sample is one written for this repository. A shape the diagram carries itself needs nothing.

The output directory must be new or empty:

output/slides/
├── page-0001.svg
├── page-0002.svg
└── conversion.json

Open the SVGs in a compatible browser, or use them as image sources in your app. Embedded images use the SVG 2 href attribute, so the renderer must be a current browser, resvg, or librsvg 2.46 or newer. Excel worksheets may span several SVG pages according to paper size and print settings. The sample workbook produces four pages. Each page of a draw.io file — one <diagram> element — becomes one SVG, cropped to the drawing.

Node.js / TypeScript

const { preview, transform } = require('document-svg')

async function main() {
  const report = await preview('slides.pptx', { maxPages: 100 })
  console.log(report.pageCount, report.needsReview)
  console.log(report.pages[0].svg)

  // Clean and minify SVG
  const cleanSvg = transform(report.pages[0].svg, {
    minify: true,
    removeMetadata: true,
    cleanPaths: true,
    stripEmptyGroups: true,
  })
}

main().catch(console.error)

preview() returns complete SVG strings and removes its temporary files. Conversion runs on a worker without blocking the JavaScript event loop.

In your frontend bundle:

import {
  createSvgPreviewUrl,
  revokeSvgPreviewUrl,
} from 'document-svg/preview-ui'

const url = createSvgPreviewUrl(svgMarkup)
imageElement.src = url

// Call this when replacing the image or disposing of the view.
const disposePreview = () => revokeSvgPreviewUrl(url)

Use an <img> for display rather than injecting arbitrary SVG into your DOM. Text inside an <img> cannot be selected or searched. The clipboard helper copies the SVG image when supported, otherwise its XML source.

English preview guide · React example · HTML export example

Python

from document_svg import convert, preview, transform

# Convert documents to SVG files
report = convert("report.docx", "output/report", max_pages=100)
print(report["page_count"])
print(report["warnings"])

# Or generate in-memory SVG pages without saving to disk
preview_report = preview("report.docx", max_pages=10)
first_svg = preview_report["pages"][0]["svg"]

# Optimize, minify, or clean SVG markup
clean_svg = transform(first_svg, minify=True, remove_metadata=True, clean_paths=True, strip_empty_groups=True)

Python conversion writes SVG files and returns a dictionary. See the Python binding guide for options and source builds.

Rust

use document_svg::{convert_path, ConvertOptions};

let report = convert_path("report.pdf", "output/report", &ConvertOptions::default())?;
println!("{} pages", report.page_count);
# Ok::<(), document_svg::Error>(())

Export SVG pages to Office, CAD, or draw.io

docsvg reverse output/slides --output slides.pptx
docsvg reverse output/slides --output slides.pdf
docsvg reverse output/diagram --output diagram.drawio
docsvg reverse output/drawing --output drawing.dxf
docsvg reverse output/slides/page-0001.svg --output preview.html
docsvg reverse output/slides/page-0001.svg --output preview.webp

Each SVG becomes a slide, document page, worksheet or diagram page. Office export embeds vector images with PNG fallbacks; it does not reconstruct the original paragraphs, cells, formulas or charts.

DXF export parses SVG vector shapes (<path>, <line>, <circle>, <rect>), text, and layer groups (<g id="layer-...">) back into standard AutoCAD Release 12 (AC1009) DXF entities (LINE, CIRCLE, ARC, TEXT).

A draw.io output restores editable shapes when the SVG carries diagram source — what draw.io writes with "Include a copy of my diagram", and what docsvg --embed-drawio-source writes:

docsvg diagram.drawio --output output/diagram --embed-drawio-source
docsvg reverse output/diagram --output same-diagram.drawio

Accuracy and safety

• Check document and page warnings. They identify unsupported features, approximations and review requirements; zero warnings is not a guarantee of pixel-identical Office rendering.
• Normal SVG text uses fonts available in the viewing environment. PDF embedded text can be outlined with --outline-embedded-pdf-text when appearance is the priority, at the cost of text editing and selection.
• Input size, ZIP entries, XML events and page count have configurable limits. ZIP-based document packages reject central directories over 100,000 entries before any part is inflated. Public upload services should also impose process-level memory and time limits.
• Existing output files are protected against overwriting. A PDF that needs a user password is rejected rather than cracked. A PDF encrypted with an empty user password — the "owner password only" form that carries permission flags such as no-printing — is opened the way any viewer opens it; those flags are declarations, not access control, and docsvg does not enforce them. Decide for yourself whether that is acceptable before converting such a file.
• Preview helpers perform conservative checks, not universal SVG sanitization.
• draw.io shape libraries are drawn from draw.io's own stencil files. Point --stencils at them to get real icons; without it, a shape from a library becomes a labelled placeholder and says so in a warning. Shapes the editor implements in code rather than as stencils stay placeholders either way. Connector routes without explicit waypoints approximate draw.io's router rather than reproducing it.

See supported features and limitations, the security policy, and performance measurements.

Editors, agents and CI

The installers build docsvg from the checkout when cargo is available, and otherwise install a checksum-verified release build. A Rust toolchain is not required.

Example request: “Use document-svg to convert this presentation into SVG previews and report any warnings.”

Claude Code also gets four commands: /document-svg:convert, /document-svg:reverse, /document-svg:preview and /document-svg:setup.

Preview changed documents in a pull request

name: Document preview
on:
  pull_request:
    paths: ['**.pdf', '**.pptx', '**.xlsx', '**.docx']
jobs:
  preview:
    uses: ryusui-hiro/document-svg/.github/workflows/document-preview.yml@main
    permissions:
      contents: read
      pull-requests: write

Every changed document is converted to SVG pages, attached to the run as an artifact, and summarised as a table of page and warning counts on the pull request.

GitHub and agent integration · Plugin installation guide

Development

cargo fmt --all -- --check
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
python3 scripts/check-publication.py

Contributing · Release operations · Changelog · License audit

License

MIT OR Apache-2.0, at your option. When redistributing the software, retain the copyright and license notices required by the license you choose.

See LICENSE, LICENSE-MIT, LICENSE-APACHE and the bundled third-party notices.