Page structure

Page structure covers the elements that control how content flows across pages: page breaks, sections, page size, margins, and page numbers. Page breaks round-trip through the pipeline. Other page structure properties are partially supported.

What you need

• Extensions: @tiptap-pro/extension-pagebreak (not in StarterKit) and Pages for paginated layout
• Export options: pageSize and pageMargins on the export extension or REST API
• Integration paths: Import and export work identically via both the editor extension and REST API. Both export paths accept pageSize and pageMargins.

Support overview

Page breaks

Page breaks fully round-trip through the pipeline. See the dedicated Page breaks page for details.

Page size and margins

Page size and margins are not imported from DOCX. The parser reads them from section properties but the Tiptap renderer discards them.

The Pages extension provides paginated layout with configurable page size and margins. For configuration details, see the Page format guide.

The export extension accepts pageSize and pageMargins options:

ExportDocx.configure({
  pageSize: {
    width: '21.0cm',
    height: '29.7cm',
  },
  pageMargins: {
    top: '2.54cm',
    bottom: '2.54cm',
    left: '3.17cm',
    right: '3.17cm',
  },
})

Values accept CSS-style units: cm, in, pt, pc, mm, px. Defaults produce an A4 page with standard Word margins.

Sections

Word documents can have multiple sections, each with its own page layout properties (size, orientation, margins, columns, headers/footers). Section support in the conversion pipeline is partial:

• Import: Section boundaries are used to detect multi-column layouts. Multi-column sections are wrapped in columns/column Tiptap nodes. Other section-level properties (size, orientation, margins) are parsed but not applied.
• Editor: Tiptap does not have a section concept, but column nodes are rendered natively.
• Export: Produces a single section. Mixed portrait/landscape or multi-section documents cannot be created.

Page numbers

Page numbers in Word are field codes (PAGE, NUMPAGES) inside headers and footers. The import translates these into canonical text tokens — {page} for PAGE and {numpages} for NUMPAGES — when the Pages extension is installed (or you opt in explicitly: placeholders: true (or { page?, total? }) on the editor command, or the placeholders={} form field on the REST API). On export, the editor extension emits {page} / {total} tokens in header/footer content as live PAGE / NUMPAGES fields so Word recalculates them on print or repagination. The REST API export does the same translation; pass placeholders: false to keep the tokens as literal text.

The Pages extension recognizes {page} and {total} by default; it does not recognize {numpages}. To make Word's NUMPAGES field render live in the editor preview after an import, configure Pages.configure({ placeholders: { total: 'numpages' } }). See DOCX import → page-number fields.

What round-trips