--- title: "Page structure" description: "How page breaks, sections, page size, margins, and page numbers are handled across the DOCX conversion pipeline." canonical_url: "https://tiptap.dev/docs/conversion/content-types/page-layout/page-structure" --- # Page structure How page breaks, sections, page size, margins, and page numbers are handled across the DOCX conversion pipeline. 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`](https://tiptap.dev/docs/pages/getting-started/overview.md) 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](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) and [REST API](https://tiptap.dev/docs/conversion/import/docx/rest-api.md). Both export paths accept `pageSize` and `pageMargins`. ## Support overview | Feature | Import | Editor | Export | | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | Page breaks | Supported | Supported (PageBreak) | Supported | | Page size | Not supported | Supported ([Pages](https://tiptap.dev/docs/pages/getting-started/overview.md)) | 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 | Supported (PAGE/NUMPAGES → `{page}`/`{numpages}` tokens, see [below](#page-numbers)) | Supported (via header/footer) | Editor extension only: `{page}`/`{total}` tokens in headers/footers emit live `PAGE`/`NUMPAGES` fields. REST API export emits literal text. | | 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](https://tiptap.dev/docs/conversion/content-types/page-layout/page-breaks.md) 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](https://tiptap.dev/docs/pages/getting-started/overview.md) provides paginated layout with configurable page size and margins. For configuration details, see the [Page format guide](https://tiptap.dev/docs/pages/core-concepts/page-format.md). The export extension accepts `pageSize` and `pageMargins` options: ```ts 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`/`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](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md#page-number-fields), or the `placeholders={}` form field on the [REST API](https://tiptap.dev/docs/conversion/import/docx/rest-api.md#page-number-fields)). On export, the [editor extension](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md) 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](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md#page-number-fields). ## 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 | Yes (editor extension export) | Word `PAGE` / `NUMPAGES` ↔ `{page}` / `{numpages}` (Pages canonical name for total is `{total}`; configure `placeholders: { total: 'numpages' }` to bridge). Re-export via the REST API does not translate the tokens — use the editor extension for round-trip. | | Columns | Partial | Import creates column nodes; export does not yet write them back |