docx-jinja2-validator

Validate Jinja2 template syntax inside .docx files — built for use with docxtpl.

Install

pip install docxlint

Usage

# single file
docxlint template.docx

# entire folder
docxlint ./templates/

# recursive (includes subfolders)
docxlint ./templates/ --recursive

# verbose (show all block tags)
docxlint ./templates/ --verbose

Or via Python module:

python -m docxlint template.docx

What it checks

Example output

Validating: template.docx  (42 KB)
────────────────────────────────────────────────────────────

1. DOCX structure
  ✓ Valid ZIP with 17 entries
  ✓ word/document.xml present

2. XML well-formedness
  ✓ word/document.xml

3. Jinja2 syntax
  ✓ word/document.xml: 6 variables, 4 block tags

4. Block tag pairing
  ✓ All for/if blocks properly closed

5. Table row tags {%tr %}
  ✓ word/document.xml: 1 table row loop(s) matched

6. Variable inventory
  → Found 6 unique variable expression(s):
    {{ objects.customer_id.name }}
    {{ objects.total_overdue_amount }}
    ...

Result
  ✓ PASSED

Exit codes

Useful for CI/CD pipelines:

docxlint ./templates/ && echo "Templates OK" || echo "Fix templates!"

Use as a library

from docxlint import validate_one
from pathlib import Path

result = validate_one(Path("template.docx"), verbose=False)
print(result.passed)   # True / False
print(result.issues)   # number of failed checks

License

MIT