Developer reference

Which one should I use?

Everything runs on your own machine, in your own process. The Node.js package converts on a background thread so the event loop keeps running, and the Python package releases the GIL while it works. No server, account or network access is involved.

Command line: docsvg

The format is chosen from the file extension, with a look at the file's first bytes when the extension is missing or generic. The command exits with 0 on success, and with 1 and a message on standard error when conversion fails.

docsvg <INPUT> --output <FOLDER> [options]
docsvg reverse <SVG or FOLDER> --output <FILE>
docsvg transform <SVG or -> --output <SVG or -> [options]

Convert: docsvg <INPUT> --output <FOLDER>

Write back: docsvg reverse

Tidy up: docsvg transform

Every input and output format →

What a conversion writes

The folder must be new or empty; existing files are never overwritten. conversion.json is the report of the whole job. The same fields come back from convert() and preview() (camelCase in Node.js).

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

Node.js

Errors reject the promise with an Error whose message starts with the kind of problem: "invalid input", "unsupported input", "safety limit exceeded" or "I/O error".

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

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

  const report = await convert('slides.pptx', 'out/slides', { jobs: 2 })
  await reverse('out/slides', 'slides-copy.pptx')
  const small = transform(firstPageSvg, { minify: true })
}

main().catch(console.error)

Options for preview() and convert()

Options for transform()

document-svg/preview-ui (runs in the browser; no native code)

Step-by-step preview guide →npm package page →

Python

Install document-svg, import document_svg. Results are plain dictionaries with the same fields as conversion.json.

from document_svg import convert, preview, reverse, transform

result = preview("report.docx", max_pages=50)
print(result["page_count"], result["needs_review"])
first_page_svg = result["pages"][0]["svg"]

report = convert("report.docx", "out/report", jobs=2)
reverse("out/report", "report-copy.docx")
small = transform(first_page_svg, minify=True)

Options for preview() and convert() (keyword-only)

Exceptions

PyPI package page →

Rust

Only the crate root (the functions above, their option and report types, Error) and the ir and svg modules are public API; internal readers can change between releases.

use document_svg::{convert_path, ConvertOptions};

fn main() -> Result<(), document_svg::Error> {
    let options = ConvertOptions { jobs: 2, ..ConvertOptions::default() };
    let report = convert_path("report.pdf", "out/report", &options)?;
    println!("{} pages, {} warnings", report.page_count, report.warnings.len());
    Ok(())
}

ConvertOptions fields

Error variants

Full API documentation on docs.rs →crates.io page →

Showing pages in a web page

Yes — the pages are ordinary SVG images, so any browser shows them. There are two ways to get them onto the screen.

1. Convert on your server or in Electron's main process with Node.js, send the SVG to the page, and show it with preview-ui (see the Node.js section and the preview guide). Works for every supported format.

2. Convert inside the browser with the WebAssembly build and its ready-made <docsvg-viewer> element. Nothing is uploaded and no server is needed. It covers PDF, Word, Excel and PowerPoint, and offers page thumbnails, zoom, fit to width or page, rotation, full screen, text search and download of the current page.

<script type="module" src="/bindings/wasm/web/docsvg-viewer.js"></script>
<docsvg-viewer thumbnails></docsvg-viewer>

<script type="module">
  const viewer = document.querySelector('docsvg-viewer')
  viewer.options = { maxPages: 200 }          // optional limits
  fileInput.addEventListener('change', () => viewer.openFile(fileInput.files[0]))
</script>

<docsvg-viewer> at a glance

• The WebAssembly build is not published as a package. Build it from bindings/wasm (Rust and wasm-bindgen are needed), then serve bindings/wasm/web from your site.
• Serve it over HTTP; opening the files with file:// does not work. A Content-Security-Policy needs 'wasm-unsafe-eval' for scripts and 'self' for workers.
• Pages are shown through Blob URLs in <img> elements; the viewer never inserts document SVG into your page.

Try the viewer in your browser →How to build and host the viewer →

Limits at a glance

Every limit protects the machine from oversized or broken files. Lower them for your use case if you like; don't raise them just to push a difficult file through.

Safety and limits →