How to Convert PDF Documents in TypeScript

This guide shows how to convert PDF content to other formats with Aspose.PDF FOSS for TypeScript. Page exports a single page as SVG or a raster image; Document exports the whole file as HTML, Markdown, or DOCX, and can validate and convert a document to PDF/A. It requires Node.js 22 or later.

Step-by-Step Guide

Step 1: Install the Package

asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.

Verify the installation by importing the Document class in a new TypeScript file — this line should resolve without error once the package is installed:

import { Document } from '@asposefoss/pdf';

Step 2: Import Required Classes

Import Document to open the file; the conversion methods used below are called directly on the returned Document and Page instances, so no further imports are needed:

import { Document } from '@asposefoss/pdf';

Step 3: Convert a Page to SVG or a Raster Image

Page.ToSvg() returns a standalone <svg> string. Page.ToImage() renders the page to raster bytes; scale is relative to the PDF’s native 72 DPI, so scale: 2 renders at 144 DPI:

import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI

Step 4: Convert a Document to HTML or Markdown

Document.ToHtml() in its default (semantic) mode reflows content from the structure tree into headings and paragraphs; pass { mode: 'fixed' } to reproduce each page as positioned SVG and absolutely-placed text instead. Document.ToMarkdown() produces GFM Markdown for the whole document:

const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages

Semantic mode reads the structure tree built by Document.GetStructTree() / Document.CreateStructTree() — on an untagged document it falls back to a heuristic body and the export loses its heading structure.

Step 5: Convert a Document to DOCX

Document.ToDocx() returns .docx bytes with content reflowed and images packaged inside; pass { mode: 'textbox' } to keep each page’s own fixed geometry instead of reflowing:

const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry

Step 6: Validate and Convert to PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level), and Document.ValidatePdfUa() return a ValidationReport describing whether the document passes the named standard. Document.ConvertToPdfA(level, opts) returns a ConversionReport listing which fix-ups it applied and which issues remain unresolved. Run the conversion on an Document.ExtractPages() copy when the live document must still be saved unconverted:

const report = doc.ValidatePdfA('2b');
console.log(report.Passed);

const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();

Common Issues and Fixes

Document.ToHtml() loses heading structure. Semantic mode walks the structure tree, so it must run after a tagging pass — either Document.AutoTag() or hand-authored tagging via StructTreeRoot.Append(). ToHtml() falls back to a heuristic body when GetStructTree() returns null.

ConvertToPdfA() changes the file you meant to keep unconverted. Run the conversion on a copy from Document.ExtractPages(), then save the copy separately — ConvertToPdfA() mutates the document it is called on.

ValidatePdfA() reports failures the first time it runs. A common cause is unembedded standard fonts and a missing /OutputIntent — check report.Passed and the individual rule findings to see which conditions were not met.

Page.ToImage() output looks low-resolution. scale is relative to 72 DPI; raise it (for example { scale: 2 } for 144 DPI) for print-quality output.

Frequently Asked Questions

What is the difference between semantic and fixed HTML export?

Semantic mode reflows the document from its structure tree into markup that reads well in a browser at any width. Fixed mode reproduces each page as positioned SVG and absolutely-placed text, matching the original layout exactly.

Does `Document.ToDocx()` preserve the original page layout?

By default ToDocx() reflows content. Pass { mode: 'textbox' } to keep each page’s own fixed geometry instead.

How do I check whether a document meets PDF/A before converting it?

Call Document.ValidatePdfA(level) (for example '2b') and inspect the returned ValidationReport — this reports the current state without modifying the document.

Can I convert only a subset of pages?

Yes — build a subset Document first with Document.ExtractPages(), then call the conversion method (ToHtml(), ToDocx(), ConvertToPdfA(), and so on) on that subset.