---
title: "Reuse Word sub-templates in C# | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/pdf-generation/word-sub-templates/"
md_url: "https://www.nutrient.io/guides/dotnet/pdf-generation/word-sub-templates.md"
last_updated: "2026-11-20T00:00:00.000Z"
description: "Learn how to reuse letterheads, terms, and signature blocks as Word sub-templates and generate a PDF using Nutrient .NET SDK."
---

# Generate documents with Word sub-templates in C#

Business documents reuse the same building blocks. Letters, quotes, and contracts share a letterhead, standard terms, and a signature block. When each template holds its own copy of these blocks, a new office address means editing every template.

Sub-templates keep each building block in a Word file of its own. The main template holds a placeholder where the block goes, and the JSON model names the file for that placeholder. Nutrient.NET SDK (formerly GdPicture.NET) inserts the file’s content when it generates the document. A sub-template is a template too, so the same JSON data fills its placeholders.

This guide generates a letter whose page header, terms, and signature come from three sub-templates, then converts the letter to PDF. It builds on the [PDF from a Word template](https://www.nutrient.io/guides/dotnet/pdf-generation/from-word-template.md) guide.

[Download sample](https://www.nutrient.io/downloads/samples/gdpicture/word-sub-templates.zip)

## How sub-templates work

Nutrient replaces a placeholder with a sub-template when the placeholder’s value in the JSON model is an object with `"_type": "docx"`. The object names the Word file with one of the following properties:

- `path`: The path to the DOCX file. A relative path starts from the application’s working directory.

- `data`: The content of the DOCX file in base64, plain or as a `data:` URI.

```json

"model": {
    "letterhead": { "_type": "docx", "path": "input_letterhead.docx" },
    "terms": { "_type": "docx", "data": "UEsDBBQABgAIAAAAIQ..." },
    "companyName": "Nutrient"
}

```

The content of the sub-template replaces the placeholder as follows:

- The paragraphs, tables, and pictures of the sub-template replace a placeholder that’s alone in its paragraph.

- A placeholder inside text splits the paragraph. The text before and after the placeholder stays in paragraphs of its own.

- Placeholders work in the body, in table cells, and in page headers and footers.

The inserted content keeps its formatting. Nutrient copies the styles, lists, pictures, links, footnotes, and bookmarks that the sub-template uses. When the main template already has a style with the same ID, the style of the main template applies, as when Word inserts a file. The headers, footers, page setup, and comments of the sub-template aren’t copied.

## Prepare the templates

The sample uses four Word files and one JSON model:

- `input_letter_template.docx`: The letter. Its page header holds `{{letterhead}}`. Its body holds the address of the customer, a table with one row per ordered item, `{{terms}}`, and `{{signature}}`.

- `input_letterhead.docx`: The company logo next to `{{companyName}}`, `{{companyStreet}}`, `{{companyCity}}`, and `{{companyPhone}}`.

- `input_letter_terms.docx`: A heading and a numbered list that uses `{{deliveryDays}}` and `{{paymentDays}}`, with a footnote.

- `input_letter_signature.docx`: `{{senderName}}` in bold and `{{senderRole}}` in a style of its own.

- `input_letter_model.json`: The data. It names the three sub-templates and holds the values of every placeholder.

The model holds the sub-templates next to the plain values:

```json

{
    "config": {
        "delimiter": {
            "start": "{{",
            "end": "}}"
        }
    },
    "model": {
        "letterhead": { "_type": "docx", "path": "input_letterhead.docx" },
        "terms": { "_type": "docx", "path": "input_letter_terms.docx" },
        "signature": { "_type": "docx", "path": "input_letter_signature.docx" },
        "companyName": "Nutrient",
        "companyStreet": "100 Main Street",
        "companyCity": "San Francisco, CA 94105",
        "companyPhone": "+1 415 555 0100",
        "date": "29 October 2026",
        "customerName": "Jane Smith",
        "customerStreet": "42 Oak Avenue",
        "customerCity": "Austin, TX 78701",
        "orderNumber": "SO-1042",
        "items": [
            { "name": "Document SDK license", "qty": "1", "price": "$4,800" },
            { "name": "Support plan", "qty": "1", "price": "$1,200" }
        ],
        "deliveryDays": "5",
        "paymentDays": "30",
        "senderName": "Alex Taylor",
        "senderRole": "Account Manager"
    }
}

```

`{{companyName}}` appears in the letterhead and in the footer of the letter. One value fills both.

## Prepare the project

Register the license before you process templates or convert documents:

```csharp

using GdPicture14;

LicenseManager license = new LicenseManager();
license.RegisterKEY(""); // Set your license key

```

## Generate the letter

Create a [`GdPictureOfficeTemplater`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPictureOfficeTemplater.html#i-syntax-CS) instance and load the JSON model. `SetTemplate` checks that the JSON holds a delimiter configuration and a model, and `Process` reads the sub-template files later:

```csharp

using GdPictureOfficeTemplater templater = new GdPictureOfficeTemplater();

GdPictureStatus status = templater.SetTemplate(File.ReadAllText("input_letter_model.json"));
ExitIfFailed(status, "Loading the template model");

```

Load the letter template:

```csharp

status = templater.LoadFromFile("input_letter_template.docx");
ExitIfFailed(status, "Loading the letter template");

```

Process the template. `Process` fills the placeholders of the letter, then opens each sub-template that a placeholder refers to, fills it from the same data, and inserts its content in place of its placeholder:

```csharp

status = templater.Process();
ExitIfFailed(status, "Processing the letter template");

```

Save the generated letter as a Word document:

```csharp

status = templater.SaveToFile("output.docx");
ExitIfFailed(status, "Saving the letter");

```

## Convert the letter to PDF

Convert the generated letter to PDF with [`GdPictureDocumentConverter`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPictureDocumentConverter.html#i-syntax-CS):

```csharp

using GdPictureDocumentConverter converter = new GdPictureDocumentConverter();

status = converter.LoadFromFile("output.docx", GdPicture14.DocumentFormat.DocumentFormatDOCX);
ExitIfFailed(status, "Loading the letter for conversion");

status = converter.SaveAsPDF("output.pdf");
ExitIfFailed(status, "Saving the PDF");

Console.WriteLine("Successfully generated the letter from its sub-templates");

```

Each step returns a `GdPictureStatus`. The following helper prints the step that failed and stops the program:

```csharp

static void ExitIfFailed(GdPictureStatus status, string step)
{
    if (status!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"{step} failed: {status}");
        Environment.Exit(1);
    }
}

```

The page header of the PDF shows the letterhead with its logo and the company address. The body shows the terms with their numbered list and footnote, followed by the signature.

## Build the model in code

The [`GdPictureOfficeTemplateBuilder`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~GdPicture14.GdPictureOfficeTemplateBuilder%601.html#i-syntax-CS) class builds the model in code. `AddSubTemplateFromFile` names a sub-template by its path, and `AddSubTemplateFromBytes` passes its content. The following excerpt shows the three sub-templates and two of the plain values:

### C#

```cs

GdPictureOfficeTemplateConfiguration configuration = new GdPictureOfficeTemplateConfiguration
{
    Delimiter = new GdPictureOfficeTemplateDelimiter
    {
        Start = "{{",
        End = "}}"
    }
};

GdPictureOfficeTemplate template = GdPictureOfficeDefaultTemplateBuilder.CreateTemplate().AddSubTemplateFromFile("letterhead", "input_letterhead.docx").AddSubTemplateFromBytes("terms", File.ReadAllBytes("input_letter_terms.docx")).AddSubTemplateFromFile("signature", "input_letter_signature.docx").AddPlaceholderReplacement("companyName", "Nutrient").AddPlaceholderReplacement("senderName", "Alex Taylor");

GdPictureStatus status = templater.SetTemplate(template, configuration);

```

## Use sub-templates in loops

Inside a loop, a sub-template reads the values of the current record first, then the values around the loop. Each record can also name a sub-template of its own. For example, a template paragraph that holds `{{#sections}}{{content}}{{/sections}}` receives one document per record from the following model. `warranty.docx` fills `{{years}}`, and `returns.docx` fills `{{days}}`, from their own records:

```json

"model": {
    "sections": [
        { "content": { "_type": "docx", "path": "warranty.docx" }, "years": "2" },
        { "content": { "_type": "docx", "path": "returns.docx" }, "days": "30" }
    ]
}

```

With the builder, call `AddSubTemplateFromFile` inside each record of `AddSection`:

### C#

```cs

GdPictureOfficeTemplate template = GdPictureOfficeDefaultTemplateBuilder.CreateTemplate().AddSection<GdPictureOfficeTemplate>("sections",
        record => record.AddSubTemplateFromFile("content", "warranty.docx").AddPlaceholderReplacement("years", "2"),
        record => record.AddSubTemplateFromFile("content", "returns.docx").AddPlaceholderReplacement("days", "30"));

```

Each copy of a sub-template gets lists of its own, so a numbered list starts at 1 in every copy.

## Error handling

`Process` returns a status other than `GdPictureStatus.OK` when a sub-template can’t be used. The whole document fails, so Nutrient never generates a letter without its letterhead. The statuses are as follows:

- `FileNotFound`: The file or its folder doesn’t exist.

- `AccessDenied`: The file can’t be read, for example because of its permissions.

- `UnsupportedFormat`: The file isn’t a Word document, or the template is a PowerPoint or Excel document.

- `InvalidParameter`: The value has neither `path` nor `data`, `data` is empty or isn’t valid base64, or a sub-template includes itself. Nutrient stops after 10 levels of nesting.

## Limitations

- Sub-templates work in Word templates only. PowerPoint and Excel templates reject a `docx` value.

- Nutrient inserts only the body of a sub-template. Placeholders in its footnotes and endnotes aren’t filled.

- Page headers and footers can’t hold footnotes or endnotes. In a header or footer, Nutrient removes the note references of a sub-template.

- Image caption numbers restart in each sub-template.

- A placeholder inside an inline content control receives only the text of the sub-template, one line per paragraph.

- `path` reads any file that the application can access. Don’t build the path from untrusted input.

## Conclusion

Sub-templates use the same steps as any Word template: load the model, load the template, process it, and save the result. The model names each sub-template, and Nutrient fills it from the same data before inserting it. To produce an accessible PDF, refer to the [Word template to PDF/UA](https://www.nutrient.io/guides/dotnet/pdf-generation/word-template-to-pdf-ua.md) guide.

Download the [sample package](https://www.nutrient.io/downloads/samples/gdpicture/word-sub-templates.zip) to run this example as-is.
---

## Related pages

- [Generate PDFs in.NET](/guides/dotnet/pdf-generation.md)
- [Create PDFs from byte arrays in C#](/guides/dotnet/pdf-generation/byte-array.md)
- [Create PDFs from scratch in C#](/guides/dotnet/pdf-generation/from-scratch.md)
- [Generate a PDF from a DOCX template in C#](/guides/dotnet/pdf-generation/from-word-template.md)
- [Generating PDF/UA from PowerPoint templates](/guides/dotnet/pdf-generation/presentation-template-to-pdf-ua.md)
- [Generating PDF/UA from Excel templates](/guides/dotnet/pdf-generation/spreadsheet-template-to-pdf-ua.md)
- [Create tagged PDFs in C#](/guides/dotnet/pdf-generation/tagged.md)
- [Create thumbnails from PDFs in C#](/guides/dotnet/pdf-generation/thumbnail-preview.md)
- [Generating PDF/UA from Word templates](/guides/dotnet/pdf-generation/word-template-to-pdf-ua.md)

