Set up sections and pages

A document contains sections. Each section controls its own page size, orientation, and margins through Section.pageSetup(). A new document starts with one section, and documents can include more sections through section breaks. Read and update section setup inside a transaction.

As of 1.17.0, page margins also include header and footer distances, so you can control how far headers and footers sit from the page edge for each section.

Document Authoring stores page dimensions in points. One point is 1/72 inch, so one inch is 72 points. For example, US Letter, which is 8.5 × 11 inches, is 612 × 792 points. A standard one-inch margin uses a value of 72.

Before you start, make sure the Document Authoring library is installed and running in your app. If you haven’t set it up yet, refer to the getting started guide.

The examples omit error handling. Add it before you use this code in production.

Read the current page setup

Use pageSize() and pageMargins() to read the current dimensions for a section:

const currentDoc = editor.currentDocument();

await currentDoc.transaction(async ({ draft }) => {
  const [section] = draft.body().sections();
  const pageSetup = section.pageSetup();

  const size = pageSetup.pageSize();
  const margins = pageSetup.pageMargins();

  console.log(`Page: ${size.width} x ${size.height} pt`);
  console.log(`Margins: ${margins.top}/${margins.right}/${margins.bottom}/${margins.left} pt`);
  console.log(`Header/footer: ${margins.header}/${margins.footer} pt`);

  return false;
});

The examples below assume currentDoc is defined as editor.currentDocument().

Set the page size

Pass the width and height in points. US Letter is 612 x 792, and A4 is 595 x 842:

await currentDoc.transaction(async ({ draft }) => {
  const [section] = draft.body().sections();

  section.pageSetup().setPageSize({ width: 595, height: 842 }); // A4

  return true;
});

Switch orientation

Document Authoring doesn’t use an orientation flag. Swap the width and height to rotate the page:

await currentDoc.transaction(async ({ draft }) => {
  const pageSetup = draft.body().sections()[0].pageSetup();
  const { width, height } = pageSetup.pageSize();

  pageSetup.setPageSize({ width: height, height: width });

  return true;
});

Set the margins

Use setPageMargins() to set any of the four page edges. A value of 72 equals 1 inch:

await currentDoc.transaction(async ({ draft }) => {
  draft.body().sections()[0].pageSetup().setPageMargins({
    top: 72,
    right: 72,
    bottom: 72,
    left: 72,
  });

  return true;
});

Set header and footer distances

Use the header and footer fields on PageMargins to control how far headers and footers are placed from the page edge. Omitted margin fields keep their current values.

await currentDoc.transaction(async ({ draft }) => {
  draft.body().sections()[0].pageSetup().setPageMargins({
    header: 36,
    footer: 36,
  });

  return true;
});

Configure every section

When a document has more than one section, sections() returns them in order. Configure each section independently. This example applies narrow margins and matching header/footer distances across the whole document.

await currentDoc.transaction(async ({ draft }) => {
  for (const section of draft.body().sections()) {
    section.pageSetup().setPageMargins({
      top: 36,
      right: 36,
      bottom: 36,
      left: 36,
      header: 36,
      footer: 36,
    });
  }

  return true;
});

Learn more

Headers and footers
Edit header and footer content for each section.

Programmatic editing
Learn how transactions work and how to use the document model.