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) andPagesfor paginated layout - Export options:
pageSizeandpageMarginson 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
pageSizeandpageMargins.
Support overview
| Feature | Import | Editor | Export |
|---|---|---|---|
| Page breaks | Supported | Supported (PageBreak) | Supported |
| Page size | Not supported | Supported (Pages) | Supported (configurable) |
| Page margins | Not supported | Supported (Pages) | Supported (configurable) |
| Sections | Partial (column configuration is extracted and applied) | Not supported | Single section only |
| Page numbers | Not supported | Supported (via header/footer) | Via header/footer content |
| Columns | Supported on import (columns/column nodes created) | Not supported | Not supported |
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.
No automatic sync between Pages and export
The export extension does not automatically read page size or margins from the Pages extension. If your editor uses a custom page format, pass matching values to the export configuration.
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/columnTiptap 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. While headers and footers are imported (see Headers and footers), page number fields are not converted because the import pipeline does not evaluate DOCX field codes.
The Pages extension supports page number placeholders ({page}, {total}) in header and footer content.
What round-trips
| Feature | Round-trips? | Notes |
|---|---|---|
| Page breaks | Yes | Requires @tiptap-pro/extension-pagebreak |
| Page size | No | Configure separately for editor (Pages) and export |
| Page margins | No | Configure separately for editor (Pages) and export |
| Sections | Partial | Column configuration survives; other section properties do not |
| Page numbers | No | Re-add through Pages extension headers/footers |
| Columns | Partial | Import creates column nodes; export does not yet write them back |