Parchment

Parchment

Parchment is a Word (.docx) generation library that combines a .NET data model with either a docx template (token replacement) or a markdown template (full content rendering), driven by liquid via Fluid, Markdig, and OpenXmlHtml.

A template belongs to its model type and is rendered by it — one template per model, no names to repeat.

Source generator (recommended)

Decorate the model class itself with [ParchmentModel] and Parchment's source generator finds the template by convention — the AdditionalFiles entry named after the type (Invoice.parchment.docx or Report.parchment.md) — validates its tokens against the model at compile time, and embeds it into the generated source. A module initializer registers it when the assembly loads, so rendering is the whole API:

[ParchmentModel]
public partial class Invoice
{
    public string Number { get; set; } = "";
    // ...
}

var store = new TemplateStore();

using var stream = new MemoryStream();
await store.Render(invoice, stream);

A markdown template's style source is found by convention too: Report.parchment.dotx, or the nearest parchment.dotx up the directory tree — embedded alongside the template.

Registering by hand

For templates the generator cannot see — content produced at runtime, per-tenant templates — register against the model type directly. The model still goes through the generator: mark it [ParchmentBindable] (and partial) so its accessors are pre-compiled without binding a template.

A docx template:

[ParchmentBindable]
public partial class Invoice
{
    // ...
}

var store = new TemplateStore();
store.RegisterDocxTemplate<Invoice>("invoice-template.docx");

using var stream = new MemoryStream();
await store.Render(invoice, stream);

A markdown template, with an optional style source — a Stream over a Word template (.dotx) whose styles the output inherits:

store.RegisterMarkdownTemplate<Report>(markdownSource, styleSource);

Render writes to a stream the caller supplies. To write straight to disk, use RenderToFile:

await store.RenderToFile(invoice, "out.docx");

Template content

The template may include:

• Substitution tokens: {{ Customer.Name }}
• Paragraph-scope loops: {% for line in Lines %} … {% endfor %}
• Loops over whole blocks: everything between the two tag paragraphs repeats, tables included. Both tags must sit in the same container — body paragraphs around a table, or one table cell; tags in different rows or cells are rejected
• Conditionals: {% if Customer.IsPreferred %} … {% endif %}

Members are resolved against the model by name. There is no snake-case translation layer, so use the property names as declared.

See the readme for full documentation.