TerraPDF

https://terrapdf.com/docs
Admin
TerraPDF is a .NET library for creating, styling, and generating PDF documents using a fluent C#...
Tokens:32,338
Snippets:332
Trust Score:5.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Header + body + footer layout example

Source: https://terrapdf.com/docs/row-and-column-layout

C# example using a Column wrapping Rows to create a page layout with header, body, and footer sections.

```csharp
container.Column(page =>
{
    page.Spacing(12);

    // Header row
    page.Item().Row(header =>
    {
        header.RelativeItem().Text("Logo");
        header.RelativeItem().Text("Title");
        header.AutoItem().Text("Page 1");
    });

    // Body content
    page.Item().Text("Main body paragraph text goes here...");

    // Footer row
    page.Item().Row(footer =>
    {
        footer.RelativeItem().Text("Company Name");
        footer.AutoItem().Text("Confidential");
    });
});
```

--------------------------------

### Two-column page layout example

Source: https://terrapdf.com/docs/row-and-column-layout

C# example nesting Rows and Columns to create a two-column page layout with a spacer between columns.

```csharp
// Side-by-side columns, each containing stacked content
container.Row(row =>
{
    row.RelativeItem().Column(left =>
    {
        left.Spacing(8);
        left.Item().Text("Left heading");
        left.Item().Text("Left body text...");
    });

    row.ConstantItem(20); // spacer

    row.RelativeItem().Column(right =>
    {
        right.Spacing(6);
        right.Item().Text("Right heading");
        right.Item().Text("Right body text...");
    });
});
```

--------------------------------

### Column Fluent API example

Source: https://terrapdf.com/docs/row-and-column-layout

C# example using the Fluent API to create a Column with three text items and vertical spacing of 10 points.

```csharp
container.Column(col =>
{
    col.Spacing(10); // vertical gap between items in points

    col.Item().Text("First line");
    col.Item().Text("Second line");
    col.Item().Text("Third line");
});
```

--------------------------------

### Header + body + footer result diagram

Source: https://terrapdf.com/docs/row-and-column-layout

ASCII diagram showing the resulting layout of the header, body, and footer example.

```text
┌──────────────────────────────────────────┐
│  Logo          Title            Page 1   │  ← Row (header)
├──────────────────────────────────────────┤
│  Main body paragraph text goes here...   │  ← Column item
├──────────────────────────────────────────┤
│  Company Name                Confidential│  ← Row (footer)
└──────────────────────────────────────────┘
```

--------------------------------

### Row layout configuration

Source: https://terrapdf.com/docs/layout

Example of using the Row component to arrange items with different sizing strategies and spacing.

```C#
container.Row(row =>
{
    row.Spacing(6);   // horizontal gap between items in points

    row.RelativeItem(2).Text("Takes 2x the share");
    row.RelativeItem(1).Text("Takes 1x the share");
    row.AutoItem().Text("Natural content width");
    row.ConstantItem(80).Text("Always 80 pt wide");
});
```

--------------------------------

### Row Fluent API example

Source: https://terrapdf.com/docs/row-and-column-layout

C# example using the Fluent API to create a Row with auto, relative, and constant sized items, with horizontal spacing of 5 points.

```csharp
container.Row(row =>
{
    row.Spacing(5); // horizontal gap between items in points

    row.AutoItem().Text("Auto-sized");        // takes its natural content width
    row.RelativeItem(2).Text("2x wide");      // takes 2x the share of remaining space
    row.RelativeItem(1).Text("1x wide");      // takes 1x the share of remaining space
    row.ConstantItem(80).Text("Fixed 80pt");  // always exactly 80 points wide
});
```

--------------------------------

### Margin, Background, Padding, and Text chain example

Source: https://terrapdf.com/docs/decorators

Shows a container with a margin of 10 pt, a lightened red background, padding of 5 pt, and text content. The red box is inset by 10 pt; text is inset 5 pt inside the red edge.

```csharp
// The red box is inset by 10 pt; text is inset 5 pt inside the red edge.
container
    .Margin(10)
    .Background(Color.Red.Lighten4)
    .Padding(5)
    .Text("Inside the box");
```

--------------------------------

### Set metadata early in Document.Create

Source: https://terrapdf.com/docs/metadata

Call metadata methods at the start of the Document.Create block to keep configuration together. Use this pattern to set title, author, and keywords before adding pages.

```C#
Document.Create(c =>
{
    // Metadata first
    c.MetadataTitle("Invoice #12345");
    c.MetadataAuthor("Acme Billing");
    c.MetadataKeywords("invoice; billing; 2025");

    // Then pages
    c.Page(...);
})
```

--------------------------------

### Install TerraPDF via dotnet CLI

Source: https://terrapdf.com/docs

Use the dotnet CLI to add the TerraPDF package to your .NET project.

```bash
dotnet add package TerraPDF
```

--------------------------------

### InvoiceDocument Template Implementation

Source: https://terrapdf.com/docs/components-and-templates

An example of an IDocument implementation for an invoice, separating data from document structure.

```C#
using TerraPDF.Core;
using TerraPDF.Helpers;
using TerraPDF.Infra;

public record InvoiceData(string Number, string ClientName, decimal Total);

public class InvoiceDocument : IDocument
{
    private readonly InvoiceData _data;

    public InvoiceDocument(InvoiceData data) => _data = data;

    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Size(PageSize.A4);
            page.Margin(2, Unit.Centimetre);
            page.DefaultTextStyle(s => s.FontSize(11));

            page.Header().Column(col =>
            {
                col.Item()
                   .Background(Color.Blue.Darken2)
                   .Padding(12)
                   .Text($"INVOICE  #{_data.Number}")
                   .Bold().FontSize(18).FontColor(Color.White);
            });

            page.Content().Column(col =>
            {
                col.Spacing(10);
                col.Item().Text($"Bill To: {_data.ClientName}").Bold();
                col.Item().Text($"Total Due: ${_data.Total:N2}").FontSize(14);
            });

            page.Footer().AlignCenter().Text(t =>
            {
                t.Span("Page ").FontSize(9).FontColor(Color.Grey.Medium);
                t.CurrentPageNumber().FontSize(9).FontColor(Color.Grey.Medium);
            });
        });
    }
}
```

--------------------------------

### CalloutBox IComponent Implementation

Source: https://terrapdf.com/docs/components-and-templates

An example of a reusable callout box component that accepts text and color parameters.

```C#
using TerraPDF.Core;
using TerraPDF.Helpers;
using TerraPDF.Infra;

public class CalloutBox : IComponent
{
    private readonly string _text;
    private readonly string _color;

    public CalloutBox(string text, string color = "#E3F2FD")
    {
        _text  = text;
        _color = color;
    }

    public void Compose(IContainer container) =>
        container
            .Margin(6)
            .Background(_color)
            .Border(1, Color.Blue.Lighten2)
            .Padding(10)
            .Text(_text).Italic().FontColor(Color.Blue.Darken2);
}
```

--------------------------------

### Combine permission flags with bitwise OR

Source: https://terrapdf.com/docs/encryption

Combines permission flags using the bitwise OR operator. This example grants printing and text copying while leaving other permissions unset.

```C#
PdfPermissions.Print | PdfPermissions.CopyText
```

--------------------------------

### Two-column layout result diagram

Source: https://terrapdf.com/docs/row-and-column-layout

ASCII diagram showing the resulting layout of the two-column page layout example.

```text
┌─────────────────────┬────┬─────────────────────┐
│  Left heading       │    │  Right heading       │
│  Left body text...  │    │  Right body text...  │
└─────────────────────┴────┴─────────────────────┘
```

--------------------------------

### Configure font families

Source: https://terrapdf.com/docs/text-and-spans

Examples of setting font families at the block, span, and page-default levels using built-in standard-14 fonts.

```C#
container.Text("Monospaced note").FontFamily("Courier");

container.Text(t =>
{
    t.Span("Serif heading ").FontFamily("Times").Bold();
    t.Span("sans-serif body").FontFamily("Helvetica");
});

page.DefaultTextStyle(s => s.FontFamily("Times").FontSize(11));
```

--------------------------------

### Rounded card example

Source: https://terrapdf.com/docs/decorators

Builds a rounded card with a light grey fill and border, containing a bold title and body text. Uses RoundedBox with radius 10, fillHexColor Grey.Lighten5, and borderHexColor Grey.Lighten2.

```csharp
col.Item()
   .Margin(6)
   .RoundedBox(radius: 10, fillHexColor: Color.Grey.Lighten5, borderHexColor: Color.Grey.Lighten2)
   .Padding(12)
   .Column(card =>
   {
       card.Item().Text("Card Title").Bold().FontSize(13);
       card.Item().PaddingTop(4).Text("Card body text.").FontColor(Color.Grey.Darken1);
   });
```

--------------------------------

### Render a Table with Columns and Data Rows

Source: https://terrapdf.com/docs/layout

Demonstrates defining columns, setting a repeating header row, and iterating through data items to populate table rows with alternating background colors.

```C#
container.Table(table =>
{
    // 1. Define columns
    table.ColumnsDefinition(cols =>
    {
        cols.RelativeColumn(4);    // proportional
        cols.RelativeColumn(1);
        cols.ConstantColumn(70);   // fixed width in points
    });

    // 2. Header row (repeated on continuation pages)
    table.HeaderRow(row =>
    {
        row.Cell().Background("#1a4a8a").Padding(6)
           .Text("Description").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignCenter()
           .Text("Qty").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignRight()
           .Text("Price").Bold().FontColor(Color.White);
    });

    // 3. Data rows
    bool shade = false;
    foreach (var item in lineItems)
    {
        string bg = shade ? Color.Grey.Lighten4 : Color.White;
        table.Row(row =>
        {
            row.Cell().Background(bg).Padding(6).Text(item.Name);
            row.Cell().Background(bg).Padding(6).AlignCenter().Text(item.Qty.ToString());
            row.Cell().Background(bg).Padding(6).AlignRight().Text($"{item.Price:N2}");
        });
        shade = !shade;
    }
});
```

--------------------------------

### Quick reference for Row and Column

Source: https://terrapdf.com/docs/row-and-column-layout

Text-based quick reference summarizing the stacking behavior of Column and Row.

```text
Column  =  vertical stacking   (think: stack of pancakes)
Row     =  horizontal stacking (think: seats in a cinema row)
```

--------------------------------

### Generating the Document

Source: https://terrapdf.com/docs/components-and-templates

Shows how to generate a PDF from an IDocument implementation to a file, byte array, or stream.

```C#
var data = new InvoiceData("2025-042", "Acme Corp.", 14_250.00m);

// To file
Document.Create(new InvoiceDocument(data)).PublishPdf("invoice.pdf");

// To byte array
byte[] pdf = Document.Create(new InvoiceDocument(data)).PublishPdf();

// To stream
Document.Create(new InvoiceDocument(data)).PublishPdf(responseStream);
```

--------------------------------

### Create Anchor-Based Bookmarks in C#

Source: https://terrapdf.com/docs/bookmarks

Use the container.Bookmark extension method to define bookmarks directly on content. Parent bookmarks must be defined before their children, and parent lookup is case-sensitive.

```csharp
Document.Create(c =>
{
    c.Page(p =>
    {
        p.Size(PageSize.A4);
        p.Content().Column(col =>
        {
            col.Item()
                .Bookmark("Chapter 1")
                .Text("Chapter 1").Bold().FontSize(18);

            col.Item()
                .Bookmark("1.1 Introduction", parentTitle: "Chapter 1")
                .Text("1.1 Introduction").Bold().FontSize(14);

            col.Item().Text("Section content...");
        });
    });
})
.PublishPdf("book.pdf");
```

--------------------------------

### ConstantItem as thin vertical divider

Source: https://terrapdf.com/docs/decorators

Use a ConstantItem inside a Row as a thin vertical divider. The example sets a 1-unit background to grey lighten2.

```C#
row.ConstantItem(1).Background(Color.Grey.Lighten2);
```

--------------------------------

### Create a Canvas and draw basic shapes

Source: https://terrapdf.com/docs/vector-graphics

Creates a fixed-height canvas of 120 points and draws a light blue filled rectangle, a darker blue outline, and a medium blue line. Coordinates use PDF points with a top-left origin. The trailing opacity parameter is optional; omitting it avoids emitting an /ExtGState resource.

```csharp
container.Canvas(120, c =>
{
    c.FillRect(0, 0, 200, 80, Color.Blue.Lighten4);
    c.StrokeRect(0, 0, 200, 80, Color.Blue.Darken2, 1.5);
    c.Line(0, 40, 200, 40, Color.Blue.Medium, 0.5);
});
```

--------------------------------

### Conditionally setting metadata with if statement

Source: https://terrapdf.com/docs/metadata

Use a conditional to set metadata only when needed, such as when the author name is available. The example shows an if statement guarding the MetadataAuthor call.

```C#
if (includeAuthor)
    c.MetadataAuthor(userName);
```

--------------------------------

### CalloutBox Usage

Source: https://terrapdf.com/docs/components-and-templates

Demonstrates how to inject the CalloutBox component into a layout item.

```C#
col.Item().Component(new CalloutBox("Note: prices exclude VAT."));
col.Item().Component(new CalloutBox("Warning: read before proceeding.", Color.Orange.Medium));
```

--------------------------------

### Combining IDocument with IComponent

Source: https://terrapdf.com/docs/components-and-templates

Demonstrates how to use IComponent implementations within an IDocument template.

```C#
public class ReportDocument : IDocument
{
    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Size(PageSize.A4);
            page.Margin(2, Unit.Centimetre);

            page.Content().Column(col =>
            {
                col.Spacing(12);
                col.Item().Component(new CalloutBox("This report is confidential."));
                col.Item().Text("Report body...").Justify();
            });
        });
    }
}
```

--------------------------------

### Margin methods for container spacing

Source: https://terrapdf.com/docs/decorators

Adds space outside the element's box, between the element and its surroundings. The margin region is always transparent — background and border start after it. Shows all sides, vertical, horizontal, and individual side overloads with optional units.

```csharp
container.Margin(10)                          // all sides, in points
container.Margin(0.5, Unit.Centimetre)        // all sides, with unit
container.MarginVertical(8)                   // top + bottom
container.MarginVertical(4, Unit.Millimetre)
container.MarginHorizontal(12)               // left + right
container.MarginTop(4)
container.MarginBottom(4)
container.MarginLeft(6)
container.MarginRight(6)
```

--------------------------------

### Apply Units to Layout Methods

Source: https://terrapdf.com/docs/page-sizes-and-units

Methods for margins and padding accept an optional Unit parameter to define measurements in units other than the default PDF points.

```C#
// Page margin
page.Margin(2, Unit.Centimetre);
page.MarginVertical(10, Unit.Millimetre);
page.MarginHorizontal(0.75, Unit.Inch);

// Container padding
container.Padding(0.5, Unit.Centimetre);
container.PaddingTop(5, Unit.Millimetre);

// Container margin
container.Margin(0.25, Unit.Inch);
container.MarginLeft(8, Unit.Millimetre);
```

--------------------------------

### Combine metadata with Bookmark for navigation

Source: https://terrapdf.com/docs/metadata

Combine metadata with bookmarks for complete navigation. Metadata provides document identity; bookmarks provide in-document navigation.

```C#
Document.Create(c =>
{
    c.MetadataTitle("User Guide");
    c.MetadataAuthor("Tech Writers Ltd");
    c.Bookmark("Introduction", 1);
    c.Bookmark("Installation", 2);
    c.Bookmark("Configuration", 3);
    // ...
});
```

--------------------------------

### Create a simple page-number-based bookmark

Source: https://terrapdf.com/docs/bookmarks

Uses the IDocumentContainer.Bookmark() overload to create a bookmark pointing to a specific page number.

```csharp
Document.Create(c =>
{
    c.Page(p =>
    {
        p.Size(PageSize.A4);
        p.Content().Text("Chapter 1 content...");
    });

    // Bookmark pointing to page 1
    c.Bookmark("Chapter 1", 1);
})
.PublishPdf("book.pdf");
```

--------------------------------

### Create a simple bar chart in C#

Source: https://terrapdf.com/docs/vector-graphics

Builds a simple bar chart from quarterly data, drawing rounded blue bars scaled to a maximum value and a light grey baseline. Canvas dimensions are in PDF points and the canvas width adapts to the container width.

```C#
(string Label, double Value)[] data =
[
    ("Q1", 38),
    ("Q2", 52),
    ("Q3", 71),
    ("Q4", 64)
];

container.Canvas(120, c =>
{
    double maxValue = 80;
    double barWidth = 40;
    double gap = 20;
    double baseline = 100;

    for (int i = 0; i < data.Length; i++)
    {
        double barHeight = data[i].Value / maxValue * 90;
        double x = i * (barWidth + gap);
        double y = baseline - barHeight;

        c.FillRoundedRect(x, y, barWidth, barHeight, 3, Color.Blue.Medium);
    }

    c.Line(0, baseline, data.Length * (barWidth + gap), baseline, Color.Grey.Lighten2, 0.5);
});
```

--------------------------------

### Bookmark(string title, int pageNumber, string parentTitle)

Source: https://terrapdf.com/docs/bookmarks

Child bookmark under the specified parent bookmark, with /XYZ destination at the page top. Defined on IDocumentContainer.

```APIDOC
## Bookmark(string title, int pageNumber, string parentTitle)

### Description
Child bookmark under the specified parent bookmark, with /XYZ destination at the page top. Defined on IDocumentContainer.

### Method
Bookmark

### Parameters
- **title** (string) - Required - Display text for the bookmark.
- **pageNumber** (int) - Required - 1-based page number of the target page.
- **parentTitle** (string) - Required - Existing bookmark title.

### Exceptions
- ArgumentNullException / ArgumentException - title or parentTitle is null/empty/whitespace.
- ArgumentOutOfRangeException - pageNumber ≤ 0.
- InvalidOperationException - parentTitle does not match any previously defined bookmark, or pageNumber is greater than total pages in the final document (thrown at save time).
```

--------------------------------

### Encrypt with view-only permissions

Source: https://terrapdf.com/docs/encryption

Creates a view-only PDF that requires a password to open. No permissions are granted, so normal users can only view the document.

```C#
container.Encrypt(new EncryptionOptions
{
    UserPassword = "readonly",
    Permissions = PdfPermissions.None
});
```

--------------------------------

### Setting Line Height Multipliers

Source: https://terrapdf.com/docs/text-and-spans

Demonstrates setting line height multipliers on text blocks to control spacing.

```C#
container.Text("Tight paragraph.").LineHeight(1.0);
container.Text("Normal paragraph.").LineHeight(1.4);
container.Text("Relaxed paragraph.").LineHeight(1.6);
container.Text("Double-spaced paragraph.").LineHeight(2.0);
```

--------------------------------

### Define Parent Bookmarks Before Children

Source: https://terrapdf.com/docs/bookmarks

Bookmarks must be defined in hierarchical order. Defining a child before its parent will throw an InvalidOperationException.

```csharp
// Good — parent first
c.Bookmark("Chapter 1", 1);
c.Bookmark("Section 1.1", 1, "Chapter 1");

// Bad — child before parent throws InvalidOperationException
c.Bookmark("Section 1.1", 1, "Chapter 1");  // ❌ parent not yet defined
c.Bookmark("Chapter 1", 1);
```

--------------------------------

### Applying Underline and Strikethrough

Source: https://terrapdf.com/docs/text-and-spans

Illustrates applying underline to whole blocks or individual spans, and combining underline with strikethrough.

```C#
// Whole block underlined
container.Text("Important notice").Underline().Bold();

// Only one span underlined in a mixed block
container.Text(t =>
{
    t.Span("Visit ");
    t.Span("TerraPDF").Underline().FontColor(Color.Blue.Medium);
    t.Span(" for more info.");
});

// Underline and strikethrough can be combined
container.Text("Deprecated").Underline().Strikethrough().FontColor(Color.Grey.Medium);
```

--------------------------------

### Check file existence for optional images

Source: https://terrapdf.com/docs/images

Guard image rendering with a file check to provide a text fallback when the file is missing.

```C#
if (File.Exists(logoPath))
    container.Image(logoPath, 100);
else
    container.Text("CompanyName").Bold().FontSize(18);
```

--------------------------------

### Add headings with .H1() and .H2() and customize TextDescriptor

Source: https://terrapdf.com/docs/table-of-contents

Use the H1–H6 extension methods on IContainer to add headings. Each method accepts plain text and returns a TextDescriptor, allowing further customization such as font color, underline, and font size. Headings can be placed anywhere a normal text element is allowed, including in Columns, decorated containers, Rows, and Tables.

```csharp
container.H1("Chapter 1")
          .FontColor(Color.Blue.Darken2)
          .Underline();

container.H2("2.1 Installation")
          .FontSize(18)
          .FontColor(Color.Grey.Darken2);
```

--------------------------------

### Define Header, Body, and Footer Structure

Source: https://terrapdf.com/docs/layout

Uses a column layout to organize a document into distinct header, body, and footer sections.

```C#
container.Column(page =>
{
    page.Spacing(10);

    // Header row
    page.Item().Row(header =>
    {
        header.RelativeItem().Text("Logo").Bold();
        header.AutoItem().Text("Page 1").FontColor(Color.Grey.Medium);
    });

    // Body
    page.Item().Text("Main content goes here.");

    // Footer row
    page.Item().Row(footer =>
    {
        footer.RelativeItem().Text("Company Name");
        footer.AutoItem().Text("Confidential").Italic();
    });
});
```

--------------------------------

### Registering and using custom fonts in C#

Source: https://terrapdf.com/docs/custom-fonts

Register custom font files at application startup and apply them to document text using the standard FontFamily API.

```csharp
using TerraPDF.Helpers;

// Register once — e.g. at application startup. Parsing is cached, so this
// is safe from a long-lived server process and reused by every document
// rendered afterwards, including concurrently.
FontFamily.Register("Brand", "fonts/Brand-Regular.ttf");
FontFamily.Register("Brand", "fonts/Brand-Bold.ttf", bold: true);

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSize.A4);
        page.DefaultTextStyle(s => s.FontFamily("Brand"));

        page.Content().Column(col =>
        {
            col.Item().Text("Héllo, Привет, Γειά σου").FontSize(18);
            col.Item().Text("Now in bold.").Bold();
        });
    });
})
.PublishPdf("branded.pdf");
```

--------------------------------

### Combine Image with decorators

Source: https://terrapdf.com/docs/images

Images can be integrated into complex layouts using the full decorator chain.

```C#
// Logo inside a padded, bordered box
container
    .Border(1, Color.Grey.Lighten2)
    .Padding(8)
    .AlignCenter()
    .Image("logo.png", 100);

// Full-width banner with a bottom accent bar
page.Header().Column(col =>
{
    col.Item().Image("banner.jpg");
    col.Item().Background(Color.Blue.Darken2).Padding(3);
});
```

--------------------------------

### Create Multi-Page Document Bookmarks

Source: https://terrapdf.com/docs/bookmarks

Demonstrates how to add bookmarks to a multi-page document using the 1-based page number. Note that an InvalidOperationException occurs if the page number exceeds the total document page count.

```C#
Document.Create(c =>
{
    // Page 1
    c.Page(p =>
    {
        p.Size(PageSize.A4);
        p.Content().Text("Cover page content");
    });

    // Page 2
    c.Page(p =>
    {
        p.Size(PageSize.A4);
        p.Content().Text("Table of Contents");
    });

    // Page 3+
    c.Page(p =>
    {
        p.Size(PageSize.A4);
        p.Content().Column(col =>
        {
            col.Item().Text("Chapter 1 — Basics");
            col.Item().Text("Chapter 2 — Advanced");
        });
    });

    // Bookmarks
    c.Bookmark("Cover",     1);
    c.Bookmark("Contents",  2);
    c.Bookmark("Chapter 1", 3);
    c.Bookmark("Chapter 2", 3);
})
.PublishPdf("book.pdf");
```

--------------------------------

### Create a bookmark with specific view position

Source: https://terrapdf.com/docs/bookmarks

Supplies a Y-coordinate in points from the top of the page to control the view position when the bookmark is activated.

```csharp
c.Bookmark("Introduction", 1, 72.0);  // starts 1 inch from page top
```

--------------------------------

### Card with coloured header

Source: https://terrapdf.com/docs/decorators

Builds a card with a coloured header using chaining: margin, border, column, background, padding, and text styling.

```C#
col.Item()
   .Margin(6)
   .Border(1, Color.Grey.Lighten2)
   .Column(card =>
   {
       card.Item()
           .Background(Color.Blue.Darken2)
           .Padding(8)
           .Text("Card Title").Bold().FontColor(Color.White);

       card.Item()
           .Padding(10)
           .Text("Card body text goes here.");
   });
```

--------------------------------

### Setting Page-Wide Default Line Height

Source: https://terrapdf.com/docs/text-and-spans

Shows how to set a default line height for an entire page using DefaultTextStyle.

```C#
page.DefaultTextStyle(s => s.FontSize(11).LineHeight(1.5));
```

--------------------------------

### Styling Page Numbers with CurrentPageNumber and TotalPages

Source: https://terrapdf.com/docs/text-and-spans

Demonstrates how to use CurrentPageNumber and TotalPages within a footer to display page counts with custom styling.

```C#
page.Footer().AlignCenter().Text(t =>
{
    t.Span("Page ").FontSize(9).FontColor(Color.Grey.Medium);
    t.CurrentPageNumber().FontSize(9).FontColor(Color.Grey.Medium);
    t.Span(" of ").FontSize(9).FontColor(Color.Grey.Medium);
    t.TotalPages().FontSize(9).FontColor(Color.Grey.Medium);
});
```

--------------------------------

### Bookmark(string title, int pageNumber)

Source: https://terrapdf.com/docs/bookmarks

Top-level bookmark with /XYZ destination at the page top. Defined on IDocumentContainer.

```APIDOC
## Bookmark(string title, int pageNumber)

### Description
Top-level bookmark with /XYZ destination at the page top. Defined on IDocumentContainer.

### Method
Bookmark

### Parameters
- **title** (string) - Required - Display text for the bookmark.
- **pageNumber** (int) - Required - 1-based page number of the target page.

### Exceptions
- ArgumentNullException / ArgumentException - title is null/empty/whitespace.
- ArgumentOutOfRangeException - pageNumber ≤ 0.
- InvalidOperationException - If pageNumber is greater than total pages in the final document (thrown at save time).
```

--------------------------------

### Encrypt and allow all permissions

Source: https://terrapdf.com/docs/encryption

Encrypts the document with a password and grants all permissions to normal users. Useful when encryption is needed for security but no restrictions are required.

```C#
container.Encrypt(new EncryptionOptions
{
    UserPassword = "open",
    Permissions = PdfPermissions.All
});
```

--------------------------------

### Bookmark(string title, int pageNumber, string parentTitle, double top)

Source: https://terrapdf.com/docs/bookmarks

Child bookmark with /XYZ destination at the specified Y position in points. Defined on IDocumentContainer.

```APIDOC
## Bookmark(string title, int pageNumber, string parentTitle, double top)

### Description
Child bookmark with /XYZ destination at the specified Y position in points. Defined on IDocumentContainer.

### Method
Bookmark

### Parameters
- **title** (string) - Required - Display text for the bookmark.
- **pageNumber** (int) - Required - 1-based page number of the target page.
- **parentTitle** (string) - Required - Existing bookmark title.
- **top** (double) - Required - Y position in points.

### Exceptions
- ArgumentNullException / ArgumentException - title or parentTitle is null/empty/whitespace.
- ArgumentOutOfRangeException - pageNumber ≤ 0 or top < 0.
- InvalidOperationException - parentTitle does not match any previously defined bookmark, or pageNumber is greater than total pages in the final document (thrown at save time).
```

--------------------------------

### Bookmark(string title, string? parentTitle = null)

Source: https://terrapdf.com/docs/bookmarks

Anchor-based bookmark on the wrapped content, with /XYZ destination resolved at render time. This is an IContainer extension method.

```APIDOC
## Bookmark(string title, string? parentTitle = null)

### Description
Anchor-based bookmark on the wrapped content, with /XYZ destination resolved at render time. This is an IContainer extension method.

### Method
Bookmark

### Parameters
- **title** (string) - Required - Display text for the bookmark.
- **parentTitle** (string?) - Optional - Existing bookmark title, if nested.

### Exceptions
- ArgumentNullException / ArgumentException - title or parentTitle is null/empty/whitespace.
- InvalidOperationException - parentTitle does not match any previously defined bookmark.
```

--------------------------------

### Bookmark(string title, int pageNumber, double top)

Source: https://terrapdf.com/docs/bookmarks

Top-level bookmark with /XYZ destination at the specified Y position in points. Defined on IDocumentContainer.

```APIDOC
## Bookmark(string title, int pageNumber, double top)

### Description
Top-level bookmark with /XYZ destination at the specified Y position in points. Defined on IDocumentContainer.

### Method
Bookmark

### Parameters
- **title** (string) - Required - Display text for the bookmark.
- **pageNumber** (int) - Required - 1-based page number of the target page.
- **top** (double) - Required - Y position in points.

### Exceptions
- ArgumentNullException / ArgumentException - title is null/empty/whitespace.
- ArgumentOutOfRangeException - pageNumber ≤ 0 or top < 0.
- InvalidOperationException - If pageNumber is greater than total pages in the final document (thrown at save time).
```

--------------------------------

### Padding vs Margin illustrated diagram

Source: https://terrapdf.com/docs/decorators

ASCII diagram illustrating the layout of margin, background/border, padding, and content within an outer slot.

```text
┌─────────────────────────────────────────┐  ← outer slot
│           margin (transparent)          │
│   ┌─────────────────────────────────┐   │
│   │       background / border       │   │
│   │   ┌─────────────────────────┐   │   │
│   │   │        padding          │   │   │
│   │   │   ┌─────────────────┐   │   │   │
│   │   │   │    content      │   │   │   │
│   │   │   └─────────────────┘   │   │   │
│   │   └─────────────────────────┘   │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

--------------------------------

### Resolve file paths with AppContext

Source: https://terrapdf.com/docs/images

Use AppContext.BaseDirectory to resolve image paths relative to the executable.

```C#
string logo = Path.Combine(AppContext.BaseDirectory, "logo.png");
container.Image(logo, 120);
```

--------------------------------

### Encrypt with AES-128 legacy algorithm

Source: https://terrapdf.com/docs/encryption

Opts into legacy AES-128 (Revision 4) encryption for compatibility with older PDF readers. Sets both passwords and grants all permissions. Use only when AES-256 output is not supported by the target viewer.

```C#
container.Encrypt(new EncryptionOptions
{
    UserPassword = "open123",
    OwnerPassword = "admin456",
    Permissions = PdfPermissions.All,
    Algorithm = EncryptionAlgorithm.Aes128
});
```

--------------------------------

### Apply Landscape Orientation

Source: https://terrapdf.com/docs/page-sizes-and-units

Use PageSize.Landscape() to swap the width and height of a specified page size constant.

```C#
page.Size(PageSize.Landscape(PageSize.A4));      // 841.89 × 595.28 pt
page.Size(PageSize.Landscape(PageSize.Letter));   // 792.00 × 612.00 pt
```

--------------------------------

### Fill available width with Image

Source: https://terrapdf.com/docs/images

The image scales to fill the full width of its container slot while keeping the original aspect ratio.

```C#
container.Image("path/to/photo.jpg");
container.Image("path/to/diagram.png");
```

--------------------------------

### Set Default Text Style in C#

Source: https://terrapdf.com/docs/text-and-spans

Sets the default font size and color for the entire page using the PageDescriptor.

```csharp
page.DefaultTextStyle(s => s.FontSize(11).FontColor(Color.Grey.Darken2));
```

--------------------------------

### Perform Manual Unit Conversion

Source: https://terrapdf.com/docs/page-sizes-and-units

Use the UnitConversion.ToPoints method to manually convert a measurement value into PDF points.

```C#
using TerraPDF.Helpers;

double pts = UnitConversion.ToPoints(2.5, Unit.Centimetre);  // ≈ 70.87 pt
```

--------------------------------

### Render single-string text

Source: https://terrapdf.com/docs/text-and-spans

The simplest way to render a single string as a block-level element.

```C#
container.Text("Hello, world!");
```

--------------------------------

### Create an internal link with container.InternalLink()

Source: https://terrapdf.com/docs/table-of-contents

Use InternalLink to create clickable internal links that jump to a specific page and vertical position. This is useful for cross-references, custom indexes, or a "return to top" link. The TOC entries themselves are also clickable via /GoTo link annotations.

```csharp
container.InternalLink(targetPageNumber, topY).Text("Jump to section");
```
Tokens:
Raw