Templify

A modern .NET library for processing Word document templates without Microsoft Word

High-performance, battle-tested document generation for .NET

---

Overview

Templify is a focused .NET library built on the OpenXML SDK that enables dynamic Word document generation and text template processing through simple placeholder replacement, conditionals, and loops. Unlike complex templating systems, Templify provides an intuitive API for the most common use cases: replacing {{placeholders}} in Word templates with actual data, and generating dynamic text content for emails and notifications.

Key Features:

• 📝 Simple placeholder syntax: {{variableName}}
• ✨ Markdown formatting in variable values: **bold**, *italic*, ~~strikethrough~~
• ↩️ Line breaks in variable values: "Line 1\nLine 2" renders as separate lines
• 🔀 Conditional blocks: {{#if}}...{{#elseif}}...{{#else}}...{{/if}}
• 🔁 Loops and iterations: {{#foreach collection}}...{{/foreach}} or {{#foreach item in collection}}...{{/foreach}}
• 🌳 Nested data structures with dot notation and array indexing
• 🎨 Automatic formatting preservation (bold, italic, fonts, colors)
• 📊 Full table support including row loops
• 📧 NEW: Text template processing for emails and notifications
• 🚀 No Microsoft Word required (pure OpenXML processing)

---

Why Templify?

The Problem

Generating Word documents programmatically is typically:

• Complex: Manual OpenXML manipulation requires 50-200 lines of code
• Error-prone: Easy to corrupt documents with incorrect XML
• Hard to maintain: Business users can't update templates
• Time-consuming: Steep learning curve for XML/OpenXML

The Solution

Templify lets you:

1. Create templates in Word - Use familiar tools, not code
2. Add simple placeholders - Just {{Name}} and {{#if}}...{{/if}}
3. Process with 3 lines of code - Clean, simple API
4. Let business users maintain templates - No developer needed

Comparison

Approach	Lines of Code	Template Creation	Maintainability	Learning Curve
Templify	~10 lines	In Word (visual)	High	Low
Manual OpenXML	~200 lines	Programmatic	Low	Steep
XSLT Templating	~150 lines	XML	Medium	High
DocX Library	~50 lines	Programmatic	Medium	Medium

Example Comparison:

Manual OpenXML (200+ lines)

using (var doc = WordprocessingDocument.Open(stream, true))
{
    var body = doc.MainDocumentPart.Document.Body;

    // Find and replace text
    foreach (var text in body.Descendants<Text>())
    {
        if (text.Text.Contains("{{Name}}"))
        {
            text.Text = text.Text.Replace("{{Name}}", customerName);
        }
    }

    // Handle tables
    foreach (var table in body.Descendants<Table>())
    {
        foreach (var row in table.Elements<TableRow>())
        {
            // ... 50+ more lines for loops
        }
    }

    // Handle conditionals - complex XML manipulation
    // ... 100+ more lines
}

Templify (10 lines)

var data = new Dictionary<string, object>
{
    ["Name"] = customerName,
    ["Items"] = orderItems,
    ["IsActive"] = true
};

var processor = new DocumentTemplateProcessor();
processor.ProcessTemplate(templateStream, outputStream, data);

Result: 95% less code, infinite times easier to maintain.

---

Quick Start

Installation

dotnet add package TriasDev.Templify

Your First Document (5 Minutes)

1. Create a Word template with placeholders:

   Hello {{Name}}!
   Your order #{{OrderId}} has been confirmed.
   

2. Process it:

   using TriasDev.Templify;
   
   var data = new Dictionary<string, object>
   {
       ["Name"] = "John Doe",
       ["OrderId"] = "12345"
   };
   
   var processor = new DocumentTemplateProcessor();
   using var templateStream = File.OpenRead("template.docx");
   using var outputStream = File.Create("output.docx");
   
   var result = processor.ProcessTemplate(templateStream, outputStream, data);

3. Done! Open output.docx and see the result.

Markdown Formatting (New!)

Variable values can include markdown syntax for text formatting:

var data = new Dictionary<string, object>
{
    ["Message"] = "My name is **Alice**" // **bold**
};

Supported markdown:

• **text** or __text__ → Bold
• *text* or _text_ → Italic
• ~~text~~ → Strikethrough
• ***text*** → Bold + Italic

The markdown formatting is automatically merged with any existing template formatting (e.g., red text + markdown bold = red bold text).

Line Breaks in Variable Values

Newline characters in variable values are automatically converted to line breaks in Word:

var data = new Dictionary<string, object>
{
    ["Address"] = "123 Main Street\nApartment 4B\nNew York, NY 10001"
};

All newline formats are supported: \n (Unix), \r\n (Windows), \r (old Mac).

Newlines work together with markdown: "**Bold line**\n*Italic line*" renders as two lines with proper formatting.

To disable (for backward compatibility):

var options = new PlaceholderReplacementOptions { EnableNewlineSupport = false };

Standalone Condition Evaluation

Use Templify's condition engine without processing Word documents:

using TriasDev.Templify.Conditionals;

var evaluator = new ConditionEvaluator();
var data = new Dictionary<string, object>
{
    ["IsActive"] = true,
    ["Count"] = 5,
    ["Status"] = "Active"
};

// Single evaluations
bool result = evaluator.Evaluate("IsActive and Count > 0", data);

// Batch evaluation (more efficient for multiple conditions)
var context = evaluator.CreateConditionContext(data);
bool r1 = context.Evaluate("IsActive");
bool r2 = context.Evaluate("Count > 3");
bool r3 = context.Evaluate("Status = \"Active\"");

Supported operators: =, !=, >, <, >=, <=, and, or, not

📖 Full Condition Evaluation Guide

📖 Full Quick Start Guide | 📚 Tutorial Series

---

Repository Structure

This repository contains multiple projects organized as a complete solution:

templify/
├── TriasDev.Templify/          # Core library (.NET 6.0+)
├── TriasDev.Templify.Tests/    # xUnit test suite (109+ tests, 100% coverage)
├── TriasDev.Templify.Gui/      # Cross-platform GUI application (Avalonia)
├── TriasDev.Templify.Converter/# CLI tool for document conversion
├── TriasDev.Templify.Benchmarks/# Performance benchmarks (BenchmarkDotNet)
└── TriasDev.Templify.Demo/     # Demo console application

---

Documentation

🌐 View Full Documentation Online →

📖 For Users

• Quick Start Guide - Get started in 5 minutes
• Tutorial Series - Step-by-step learning path
• FAQ - Common questions and answers
• API Reference - Complete feature documentation
• Examples Collection - 1,900+ lines of code samples

🏗️ For Developers

• Architecture Guide - Design patterns and technical decisions
• Performance Benchmarks - Speed and optimization details
• CLAUDE.md - Development guide for AI-assisted coding
• Contributing Guide - How to contribute to Templify

---

Development Setup

Prerequisites

Prerequisites:

• .NET 6.0 SDK or later
• Git
• Python 3.11+ (for documentation)

Clone and build:

git clone git@github.com:TriasDev/templify.git
cd templify
dotnet build templify.sln

Run tests:

dotnet test TriasDev.Templify.Tests/TriasDev.Templify.Tests.csproj

Run demo:

dotnet run --project TriasDev.Templify.Demo/TriasDev.Templify.Demo.csproj

Build documentation locally:

# Install dependencies
pip3 install -r requirements.txt

# Build static site
mkdocs build

# Or serve with live reload
mkdocs serve
# Opens at http://127.0.0.1:8000/templify/

Projects

📚 Templify (Core Library)

The main template processing library. Provides DocumentTemplateProcessor for replacing placeholders, evaluating conditionals, and processing loops in Word documents.

Architecture: Visitor pattern with context-aware evaluation Target: .NET 6.0+ Dependencies: DocumentFormat.OpenXml 3.3.0

📖 Full Library Documentation | 🏗️ Architecture Details | 📝 Code Examples

🖥️ GUI Application

Cross-platform desktop application built with Avalonia for visual template editing and processing.

Run the GUI:

dotnet run --project TriasDev.Templify.Gui/TriasDev.Templify.Gui.csproj

Features:

• Visual template editor
• Data input and preview
• Real-time template processing
• Cross-platform (Windows, macOS, Linux)

🔧 CLI Converter Tool

Command-line tool for migrating OpenXMLTemplates documents to Templify format, with analysis, validation, and cleanup capabilities.

Run the converter:

# Full command
dotnet run --project TriasDev.Templify.Converter/TriasDev.Templify.Converter.csproj -- [command] [options]

# Or use helper scripts (recommended)
./scripts/[command].sh [options]          # macOS/Linux
scripts\[command].cmd [options]           # Windows

Available Commands:

• analyze - Inspect OpenXMLTemplates documents and identify content controls

  ./scripts/analyze.sh template.docx
  ./scripts/analyze.sh template.docx --output report.md

• convert - Convert OpenXMLTemplates to Templify format

  ./scripts/convert.sh template.docx
  ./scripts/convert.sh template.docx --output new-template.docx

• validate - Validate Word document structure and schema

  ./scripts/validate.sh template.docx

• clean - Remove Structured Document Tag (SDT) wrappers

  ./scripts/clean.sh template.docx
  ./scripts/clean.sh template.docx --output cleaned.docx

Migration Workflow Example:

# Step 1: Analyze the template
./scripts/analyze.sh old-template.docx

# Step 2: Review the analysis report
cat old-template-analysis-report.md

# Step 3: Convert to Templify format
./scripts/convert.sh old-template.docx

# Step 4: Validate the converted document
./scripts/validate.sh old-template-templify.docx

# Step 5: Test with actual data
# Use demo or custom code with Templify library

Batch Processing Example:

# Convert all templates in a directory
for template in templates/*.docx; do
  ./scripts/convert.sh "$template"
done

📖 Full Converter Documentation | 📜 Script Usage Guide

Migrating from OpenXMLTemplates

The converter automatically translates OpenXMLTemplates content control tags to Templify placeholders:

OpenXMLTemplates	Templify
variable_CompanyName	{{CompanyName}}
conditionalRemove_IsActive	{{#if IsActive}}...{{/if}}
conditionalRemove_Count_gt_0	{{#if Count > 0}}...{{/if}}
repeating_LineItems	{{#foreach LineItems}}...{{/foreach}}

Benefits of migrating:

• ✅ Simpler template creation (no content controls required)
• ✅ Human-readable placeholders
• ✅ Better Word compatibility (no SDT corruption)
• ✅ Modern architecture with better performance
• ✅ Easier maintenance and debugging

🎯 Demo Application

Console application demonstrating all library features with comprehensive examples.

Run demos:

dotnet run --project TriasDev.Templify.Demo/TriasDev.Templify.Demo.csproj

Includes demonstrations of:

• Basic placeholder replacement
• Nested data structures
• Conditional blocks
• Loop processing
• Table operations
• Formatting preservation
• Complex real-world scenarios

⚡ Benchmarks

Performance testing using BenchmarkDotNet for measuring template processing speed.

Run benchmarks:

dotnet run --project TriasDev.Templify.Benchmarks/TriasDev.Templify.Benchmarks.csproj -c Release

Benchmark categories:

• Placeholder replacement
• Conditional evaluation
• Loop processing
• Complex scenarios

📊 Performance Details

✅ Tests

Comprehensive test suite with 109+ tests covering all features.

Test coverage:

• Unit tests: 70 (component-level testing)
• Integration tests: 39 (end-to-end scenarios)
• Coverage: 100%

Run all tests:

dotnet test TriasDev.Templify.Tests/TriasDev.Templify.Tests.csproj

Run specific test:

dotnet test --filter "FullyQualifiedName~PlaceholderVisitorTests"

Run with coverage:

dotnet test --collect:"XPlat Code Coverage"

Documentation

Comprehensive documentation is organized by purpose:

• 📖 Library README - API reference, usage guide, feature documentation
• 🏗️ ARCHITECTURE.md - Design patterns, visitor pattern flow, technical decisions
• 📝 Examples.md - Extensive code samples and use cases
• ⚡ PERFORMANCE.md - Benchmark results and optimization details
• 🤖 CLAUDE.md - Development guide for AI-assisted coding
• 📋 TODO.md - Feature roadmap and implementation status
• 🔄 REFACTORING.md - Refactoring history and decisions

Building & Testing

Build entire solution

# Debug build
dotnet build templify.sln

# Release build
dotnet build templify.sln -c Release

Run all tests

dotnet test TriasDev.Templify.Tests/TriasDev.Templify.Tests.csproj --verbosity normal

Clean solution

dotnet clean templify.sln

Restore dependencies

dotnet restore templify.sln

Development

Requirements

• .NET 6.0 SDK or later
• Visual Studio 2022 (optional, for GUI development) or Rider
• Git for version control

Project Guidelines

• Code style: Follow existing conventions (see CLAUDE.md)
• Testing: Maintain 100% test coverage for new features
• Documentation: Update relevant README and documentation files
• Commits: Use descriptive commit messages

For AI-Assisted Development

This repository includes CLAUDE.md with comprehensive guidance for AI coding assistants:

• Common commands and workflows
• Architecture overview
• Design patterns and conventions
• Testing strategies
• Troubleshooting common issues

🤖 Read CLAUDE.md for AI-assisted development guidance

Requirements

• .NET 6.0 or later
• DocumentFormat.OpenXml 3.3.0 (automatically restored)
• Avalonia 11.3.8 (for GUI project)
• xUnit (for test project)
• BenchmarkDotNet (for benchmarks)

Architecture Highlights

Templify uses a visitor pattern architecture for clean, extensible document processing:

• DocumentWalker - Unified document traversal
• Visitors - ConditionalVisitor, LoopVisitor, PlaceholderVisitor
• Evaluation Context - Hierarchical variable resolution with loop scoping
• PropertyPathResolver - Nested data structure navigation

Processing order: Conditionals → Loops → Placeholders (enables conditionals inside loops and nested loops)

🏗️ Full Architecture Documentation

Design Philosophy

Templify prioritizes:

1. Simplicity - Focus on common use cases (placeholder replacement, conditionals, loops)
2. Maintainability - Small, composable classes with single responsibilities
3. Testability - Pure functions, dependency injection, 100% test coverage
4. Explicit behavior - No magic, predictable results
5. Fail-fast - Clear error messages, no silent failures

About

Templify is created and maintained by TriasDev GmbH & Co. KG.

Production-Tested

Templify is battle-tested in production, processing thousands of documents daily with enterprise-grade reliability and performance.

Why Open Source?

We believe in giving back to the .NET community and providing developers with a modern, maintainable alternative to legacy Word templating solutions.

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or suggesting enhancements, your contributions are appreciated.

How to Contribute

1. Report bugs - Open an issue with detailed reproduction steps
2. Suggest features - Share your ideas through GitHub issues
3. Submit pull requests - Fork the repo, make changes, and submit a PR
4. Improve documentation - Help make our docs clearer and more comprehensive

Getting Started

• Read our Contributing Guide for detailed guidelines
• Check our Code of Conduct for community standards
• Review CLAUDE.md for development workflows and architecture

Development Requirements

• .NET 6.0 SDK or later
• All contributions must maintain 100% test coverage
• Follow existing code style and conventions
• Update documentation for any new features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright © 2025 TriasDev GmbH & Co. KG

Related Projects

• OpenXMLTemplates (predecessor) - Original templating library (content controls-based)

---

Getting Started: For library usage, see TriasDev.Templify/README.md Contributing: See CONTRIBUTING.md for guidelines and CLAUDE.md for development workflows Architecture: For technical deep-dive, see ARCHITECTURE.md