Known limitations

Papyra publishes its gaps instead of hiding them. This page lists the limitations that most often matter in practice; what’s still open is on the roadmap.

All foundational gaps have shipped

Every foundational feature is delivered - each with residual limitations worth knowing:

• Rich table cells - cells take the full paragraph API (mixed runs, links, images) and can nest a table (tables guide). In XLSX, run styling collapses to the cell-level style, images float as anchored drawings, and nested cells flatten into the worksheet grid (containment is visual only). Rows hosting a nested table never split across pages, and header rows inside a nested table don’t repeat.

• Word wrapping - measured line breaking in paragraphs and table cells, with soft hyphens, CJK breaking (kinsoku), and opt-in pattern hyphenation. Pattern hyphenation covers seven languages (de, en, es, fr, it, nl, pt) and applies to single-style all-letter words only; a word with no usable break point still overflows its column - the companion app flags exactly those cases.

• Page numbers and dynamic fields - see headers and footers. Legal in bands and in body content (paragraphs, cells, lists, rows); PDF resolves exact body values via a bounded two-pass layout, DOCX uses native Word fields, HTML/XLSX drop body page fields (no page concept) and print the render date literally. Footnote bodies reject fields.

• Rich headers/footers with a first-page variant - bands take rows, tables, images, and lines. The reserved band height is uniform across the pages of a section (the taller of regular and first-page band), and an XLSX field-band can only carry text.

• Sections - see sections. Per-section page size, orientation, margins, and bands; page numbers run continuously across sections, and DOCX carries each non-final section’s properties in a small empty paragraph (a table cannot host them), which can add a blank line when a section’s last page is exactly full.

• HTML output - see HTML output. One self-contained reflowable file; header/footer bands and watermarks render once per section flow rather than per printed page, page-number fields are omitted (a reflowable document has no page count, and the CSS counters that could supply one in print are unimplemented in Chrome and Firefox), custom fonts are named rather than embedded, and adjacent cell borders collapse.

• Image format parity - every format the image library decodes (JPEG, PNG, GIF, BMP, TIFF, WebP, TGA, PBM, QOI; transparency included, CMYK JPEG transcoded to RGB) renders in all four output formats; non-JPEG/PNG sources are converted to PNG at compose time, animated/multi-page sources keep the first frame; XLSX anchors images over the grid. SVG has its own Svg(...) API in the optional Papyra.Svg package - vector output in PDF where the SVG’s features allow it, a high-resolution raster otherwise, and native SVG with a PNG fallback in DOCX/XLSX.

Also not there yet

• Thick dashed and weighted dotted borders in XLSX - Excel’s single border-style axis has no thick-dashed entry and only one dotted weight, so dashed borders above 1pt degrade to mediumDashed and dotted borders drop their width; the other formats render width and style independently
• Spacing between non-paragraph blocks - ParagraphStyle spaces paragraphs; tables/rows still need a spacer paragraph - planned (roadmap)
• Keep-together/keep-with-next degrade for content taller than one page (a chain places its members individually, an oversized table/list splits as usual), and DOCX approximates whole-table keep via a keepNext chain - Word may still split extreme cases
• True intermediate font weights outside PDF and HTML - FontWeight.Light…BLACK render as real cuts in PDF with per-weight registered fonts and as CSS font-weight values in HTML; built-ins and DOCX/XLSX collapse to regular/bold
• Per-section page-number restart - sections number continuously across the document; sheet names in XLSX are always Sheet1…SheetN (configurable names are planned - roadmap), and the Designer app deliberately does not edit sections
• Radial gradients and per-stop gradient opacity - page backgrounds take a linear ramp with one opacity for every stop (SVG backgrounds via Papyra.Svg can carry radial gradients) - planned (roadmap)
• Right-to-left text has three edges worth knowing: the built-in fonts cover Hebrew but not Arabic (register an Arabic font - see fonts); copying right-to-left text out of a PDF yields visual order, because a content stream stores glyphs in painting order and only a bidi-aware extractor recovers the original; and the explicit Unicode direction controls (LRE/RLE/LRO/RLO/PDF and the isolates) are ignored in favor of ParagraphStyle.Direction - see right-to-left text
• Invoice-XML generation/validation - e-invoicing embeds your ZUGFeRD/Factur-X XML but does not create or check it; attachments require PDF/A-3 (no PDF/A-4f)

Format divergences to be aware of

• A family Papyra cannot embed is measured with the closest built-in face but passed to DOCX, XLSX and HTML under its own name, so the reader’s real font may have different metrics than the layout assumed - see fonts for the mapping, and register the font if the two must agree

• XLSX collapses per-run styling to one style per line - a worksheet cell holds a single style (so sub/superscript styles the whole cell); letter spacing has no XLSX equivalent and is dropped

• Strikethrough/underline lines in PDF are always black and 1 unit thick, regardless of the run color

• Paragraph layout options flatten per format: XLSX keeps background (cell fill) and left indent (native indent, ≈9pt steps) but drops spacing/line spacing; DOCX blends translucent paragraph backgrounds to white; paragraph backgrounds inside table cells are ignored everywhere (use CellStyle.BackgroundColor)

• Repeating table footers work in PDF and HTML (<tfoot>); DOCX has no OOXML equivalent

• Table-of-contents page numbers appear in PDF only - Word computes its own on refresh, and HTML has no pages. A DOCX heading with an explicit title override shows the paragraph’s own text after Word rebuilds the field, since that is what Word collects

• Watermarks render one centered instance per page (no tiling) and images are never rotated; XLSX ignores them entirely. DOCX sizes the text shape by a per-character approximation (not measured glyphs, so proportions can drift from PDF) and approximates image opacity as Word’s “washout” preset

• Page backgrounds diverge most of all: XLSX flattens a gradient to its first stop and ignores an image background outright (Excel’s sheet picture tiles and never prints); DOCX uses a full-page shape in the header rather than Word’s native Page Color, so the Page Color UI does not reflect it and a translucent color is pre-blended against white; and in HTML print, @page owns the margins, so the background covers the printable area rather than bleeding to the sheet edge. Image fit modes only differ fully in PDF and HTML - a VML fill is either stretched or tiled, so DOCX renders COVER/CONTAIN/STRETCH identically (stretched) and tiles at the image’s own DPI. CONTAIN leaves uncovered bands when the image’s aspect ratio does not match the page - there is no backdrop color to fill them

• Footnotes land on their marker’s page in PDF only - Word paginates and numbers its own, and HTML and XLSX have no page, so both gather notes as endnotes at the end of a section. PDF draws no back-link (the note is on the same page, and its link annotations carry URLs only) and a link inside a note is not clickable there; PDF also caps the note area at half the page and lets an overlong note overflow rather than leave no room for content, whereas Word splits the note natively. A note body takes text and links but no images, wrapped lines get no hanging indent, and in XLSX a marker inside a table cell is dropped because the cell’s plain-text projection runs before the numbers exist

See the feature support matrix for the complete per-format picture.