Sections

A section is a consecutive range of content with its own page setup. Use one when part of a document needs a different page than the rest - a landscape appendix in a portrait report, a wide-margin cover, a chapter with its own header.

var document = Document.Create(doc => doc
    .PageSize(PageSize.A4)
    .Margin(48f)
    .Header(h => h.Text("Quarterly report"))

    .Paragraph(p => p.Text("Portrait body text."))

    .Section(s => s
        .Orientation(PageOrientation.Landscape)
        .Header(h => h.Text("Appendix A"))
        .Table(t => t
            .Columns(6)
            .Header(r => r.Cell("Region").Cell("Q1").Cell("Q2").Cell("Q3").Cell("Q4").Cell("Total"))
            .Row(r => r.Cell("North").Cell("12").Cell("14").Cell("11").Cell("18").Cell("55")))));

A section always starts on a new page. No explicit PageBreak() is needed before one.

Implicit sections

Content added directly on the document - before, between, or after Section(...) calls - forms its own implicit section using the document-level page setup. Documents that never call Section(...) behave exactly as before; sections are purely additive.

doc.Paragraph(p => p.Text("Cover"))       // implicit section 1 (document page setup)
   .Section(s => s.PageSize(PageSize.A3)) // section 2
   .Paragraph(p => p.Text("Back matter")) // implicit section 3 (document page setup again)

Inheritance and opt-out

Every setting a section does not set is inherited from the document: page size, orientation, margins, header, footer, the first-page variants, and the page background.

doc.PageSize(PageSize.A4)
   .Margin(48f)
   .Header(h => h.Text("Shared header"))
   .Section(s => s.Margin(120f)          // only the margin differs; A4 and the header carry over
       .Paragraph(p => p.Text("Wide margins")));

To remove an inherited band rather than replace it, pass an empty callback - the same idiom FirstPageHeader already uses, and one that PageBackground follows too:

doc.Section(s => s
    .Header(h => { })                     // no header on this section's pages
    .PageBackground(_ => { })             // and no inherited page background either
    .Paragraph(p => p.Text("Bare pages")));

Note that Margin(Thickness.Zero) is a real override (zero margins), not “inherit”. The empty-band idiom means “suppress” on a section; on the document itself an empty Header(h => { }) simply produces an empty band, as it always has.

Orientation

Orientation(...) normalizes the effective page size instead of swapping it blindly:

Call	Effective page
PageSize(PageSize.A4)	595 × 842 (as given)
PageSize(PageSize.A4.Landscape())	842 × 595 (as given)
PageSize(PageSize.A4).Orientation(LANDSCAPE)	842 × 595
PageSize(PageSize.A4.Landscape()).Orientation(PORTRAIT)	595 × 842

So PORTRAIT always makes the smaller dimension the width and LANDSCAPE the larger one, whichever order the PageSize was written in. Leaving orientation unset uses the PageSize dimensions literally, which is why PageSize.A4.Landscape() keeps working on its own.

Orientation(...) is available on both the document and a section; a section inherits the document’s orientation unless it sets its own.

Page numbers

Page numbering runs continuously across sections - a PageXofY() footer on page one of the second section of a three-page document reads “Page 2 of 3”. Per-section restart is not supported.

First-page headers and footers

FirstPageHeader / FirstPageFooter apply to the first page of each section that has them after inheritance. This matches Word, where the “different first page” flag is a per-section property. A consequence worth knowing: a document-level FirstPageHeader is inherited by every section and therefore reappears on each section’s first page. Opt a section out with an empty band:

doc.FirstPageHeader(h => h.Text("Cover banner"))
   .Paragraph(p => p.Text("Cover"))
   .Section(s => s
       .FirstPageHeader(h => { })         // no cover banner at the start of this section
       .Paragraph(p => p.Text("Chapter 1")));

Page size is required

A sectioned document must have an effective page size: set PageSize on the document, or on every section. Building one without throws InvalidOperationException. (The page-less mode, where a document without PageSize renders as one continuous PDF page, is only available without sections.)

Per-format behavior

Format	Behavior
PDF	Each section’s pages carry their own /MediaBox, margins, and bands. Mixed page sizes in one file are fine.
DOCX	One native w:sectPr per section - Word’s own section model, so the document stays fully editable. w:orient is emitted for landscape pages.
XLSX	One worksheet per section (Sheet1, Sheet2, …), each with its own print setup, margins, and print header/footer.

Note

DOCX hosts every non-final section’s properties in a small empty paragraph at the end of that section (a table cannot carry section properties in OOXML). If a section’s last page is exactly full, Word may show one extra blank line or page.

Sheet names are always Sheet1…SheetN - sections have no name property yet. The Designer app deliberately does not edit sections; build them through the fluent API.

KeepWithNext() does not chain across a section boundary: each section paginates on its own, so the flag on a section’s last block has no following block to hold onto.