Document structure

Version 6.1.0

In this article

This article describes how a MigraDoc document is structured and how you can apply the desired structure for your document.

Introduction

A MigraDoc document is organized in sections which contain all the document’s content. But pages do not yet exist when you create a MigraDoc document. So do not think in pages. Pages will be created when the document is finally rendered to PDF. No pages will be created when rendering to RTF.

MigraDoc documents are highly dynamic. The count of pages required to render a PDF can change at any time before you start rendering. Everything becomes different if you change the page size, the font size, the font name, or other properties.

However, there are some ways to control the document’s page flow (see Page control for more information).

MigraDoc can be used like one would use a Word processor to write a book: Think styles, do not think text attributes.

When creating a book about software, create styles for code blocks, for class names, for properties, for literals.

Your document may have hundred occurrences of class names and thousand instances of literals, but there is only one spot that defines how they look: The corresponding style.

Also define styles for headings, for regular paragraphs, for quoted paragraphs, and other styles you need. MigraDoc comes with about 20 predefined styles, but you can add more styles and change the predefined styles as needed. With an ideal MigraDoc document, you specify font names and font sizes only when defining the styles.

For more information about formatting and styles see Formatting.

Document

The Document object in MigraDoc represents a whole document assembled with the MigraDoc Document Object Model (DOM).

A Document object can be created simply by using its constructor:

// Create a new MigraDoc document.
var document = new Document();

See full SimpleDocument sample in DocumentStructure in PDFsharp.Sample repository. Show resulting PDF

Sections

All contents of a document are organized in sections. So a not empty document must have at least one section.

You can create a new Section object by adding a new one to the document:

// Add a section to the document.
var section = document.AddSection();

See full SimpleDocument sample in DocumentStructure in PDFsharp.Sample repository. Show resulting PDF

A section represents a part of the document’s content. Usually, one Section object is used for one chapter of the document.

For some reasons it can also be helpful to organize a part of the document’s content in a Section object. The page setup or headers and footers, for example, can only be defined for the whole document or a specific section. So, if you want to vary these settings just for some pages, you have to wrap the respective content in an own Section object.

You can always access the last added section of a document with document.LastSection.

Further structuring

In a section, you can add Paragraph objects to write some text:

// Add a paragraph to the section.
var paragraph = section.AddParagraph("Some text.");

See full SimpleDocument sample in DocumentStructure in PDFsharp.Sample repository. Show resulting PDF

You can always access the last added paragraph of a section with section.LastParagraph.

Furthermore, you can add Text or FormattedText objects to a paragraph to work with different inline formattings (see Contents / Text for more information).

There is also a bunch of other contents, you can add to a section, like tables, images and other objects (see Contents for more information). Usually, you can call a function like AddTable, AddImage or similar, to add a new object to the document or to an object of the document. This function will typically return the currently created and added object for further processing.

However, in MigraDoc Document Object Model (DOM) you can not nest sections to achieve a deeper document structure. Inside a section, you can work with headings to structure your document - just like you do in Microsoft Word.

Headings & document outline

In MigraDoc, there’s no heading class. To create a heading, you can instead add a paragraph and use one of the heading styles defined in the StyleNames enum:

// Add a heading of level 1 to the section.
var heading = section.AddParagraph("Heading 1");
heading.Style = StyleNames.Heading1;

See full HeadingsAndDocumentOutline sample in DocumentStructure in PDFsharp.Sample repository. Show resulting PDF

The style names Heading1 to Heading9 are predefined using the OutlineLevel enum values Level1 to Level9. Paragraphs set to an outline level other than the default value BodyText will occur on the PDF’s document outline. Most PDF viewers show that document outline on the left side of the document for faster navigation. So using the heading styles, your document outline will automatically get filled.

Note that without editing these styles, all headings will look the same. For more information about styles see Formatting.

You should always use the heading styles in the logical order to avoid problems with the document outline display. Following this rule, you could for example add those sections and its objects:

// Add a first section for "Heading 1" to the document.
var section1 = document.AddSection();

// Add a heading of level 1 to the first section.
var heading1 = section1.AddParagraph("Heading 1");
heading1.Style = StyleNames.Heading1;

// Add "Heading 1" content.
var paragraph1 = section1.AddParagraph("Content for heading 1");

// Add a heading of level 2.
var heading1_1 = section1.AddParagraph("Heading 1.1");
heading1_1.Style = StyleNames.Heading2;

// Add "Heading 1.1" content.
…

// Add another heading of level 2.
var heading1_2 = section1.AddParagraph("Heading 1.2");
heading1_2.Style = StyleNames.Heading2;

// Add "Heading 1.2" content.
…

// Add a heading of level 3.
var heading1_2_1 = section1.AddParagraph("Heading 1.2.1");
heading1_2_1.Style = StyleNames.Heading3;

// Add "Heading 1.2.1" content.
…

// Add a second section for "Heading 2" to the document.
var section2 = document.AddSection();

// Add another heading of level 1 to the second section.
var heading2 = section2.AddParagraph("Heading 2");
heading2.Style = StyleNames.Heading1;

// Add "Heading 2" content.
…

See full HeadingsAndDocumentOutline sample in DocumentStructure in PDFsharp.Sample repository. Show resulting PDF

Table of contents

A table of contents can be manually created by using BookmarkFields and Hyperlinks (see Contents / Hyperlinks for more information).