Docx Generator

Quick Start

Two Modes of Operation

1. Template Mode: Modify existing branded templates

   • Analyze template to find placeholders
   • Replace {{PLACEHOLDERS}} with actual content

2. Scratch Mode: Create documents from nothing using JSON specifications

Instructions

Mode 1: Template-Based Generation

Step 1a: Analyze the Template

Extract text inventory to understand what can be replaced:

deno run --allow-read scripts/analyze-template.ts corporate-template.docx > inventory.json

Output (inventory.json):

{
  "filename": "corporate-template.docx",
  "paragraphCount": 25,
  "tableCount": 2,
  "imageCount": 1,
  "paragraphs": [
    {
      "index": 0,
      "style": "Title",
      "fullText": "{{DOCUMENT_TITLE}}",
      "runs": [
        { "text": "{{DOCUMENT_TITLE}}", "bold": true, "fontSize": 28 }
      ]
    }
  ],
  "placeholders": [
    { "tag": "{{DOCUMENT_TITLE}}", "location": "paragraph", "paragraphIndex": 0 },
    { "tag": "{{AUTHOR}}", "location": "footer-default", "paragraphIndex": 0 },
    { "tag": "${date}", "location": "table", "tableIndex": 0, "cellLocation": "R1C2" }
  ]
}

Step 1b: Create Replacement Specification

Create replacements.json:

{
  "textReplacements": [
    { "tag": "{{DOCUMENT_TITLE}}", "value": "Q4 2024 Financial Report" },
    { "tag": "{{AUTHOR}}", "value": "Finance Department" },
    { "tag": "${date}", "value": "December 15, 2024" },
    { "tag": "{{COMPANY}}", "value": "Acme Corporation" }
  ],
  "includeHeaders": true,
  "includeFooters": true
}

Step 1c: Generate Output

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  corporate-template.docx replacements.json output.docx

Mode 2: From-Scratch Generation

Step 2a: Create Specification

Create spec.json:

{
  "title": "Quarterly Report",
  "creator": "Finance Team",
  "styles": {
    "defaultFont": "Calibri",
    "defaultFontSize": 11
  },
  "sections": [
    {
      "header": {
        "paragraphs": [
          { "text": "Acme Corporation", "alignment": "right" }
        ]
      },
      "footer": {
        "paragraphs": [
          { "text": "Confidential", "alignment": "center" }
        ]
      },
      "content": [
        {
          "text": "Q4 2024 Financial Report",
          "heading": 1,
          "alignment": "center"
        },
        {
          "runs": [
            { "text": "Executive Summary: ", "bold": true },
            { "text": "This report provides an overview of our financial performance for Q4 2024." }
          ]
        },
        { "pageBreak": true },
        {
          "text": "Revenue Breakdown",
          "heading": 2
        },
        {
          "rows": [
            {
              "cells": [
                { "content": [{ "text": "Category" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Amount" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Change" }], "shading": "DDDDDD" }
              ],
              "isHeader": true
            },
            {
              "cells": [
                { "content": [{ "text": "Product Sales" }] },
                { "content": [{ "text": "$1,250,000" }] },
                { "content": [{ "text": "+15%" }] }
              ]
            },
            {
              "cells": [
                { "content": [{ "text": "Services" }] },
                { "content": [{ "text": "$750,000" }] },
                { "content": [{ "text": "+8%" }] }
              ]
            }
          ],
          "width": 100,
          "borders": true
        }
      ]
    }
  ]
}

Step 2b: Generate Document

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.docx

Examples

Example 1: Contract Generation

Scenario: Generate contracts from a branded template.

Steps:

# 1. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts contract-template.docx --pretty

# 2. Create replacements.json with client data
# 3. Generate contract
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  contract-template.docx replacements.json acme-contract.docx

Example 2: Report with Tables

Scenario: Generate a data report with tables and formatting.

spec.json:

{
  "title": "Sales Report",
  "sections": [{
    "content": [
      { "text": "Monthly Sales Report", "heading": 1 },
      { "text": "January 2025", "heading": 2 },
      {
        "runs": [
          { "text": "Total Sales: ", "bold": true },
          { "text": "$125,000", "color": "2E7D32" }
        ]
      }
    ]
  }]
}

Example 3: Letter with Headers/Footers

Scenario: Create a formal letter with letterhead.

spec.json:

{
  "sections": [{
    "header": {
      "paragraphs": [
        { "text": "ACME CORPORATION", "alignment": "center", "runs": [{"text": "ACME CORPORATION", "bold": true, "fontSize": 16}] },
        { "text": "123 Business Ave, City, ST 12345", "alignment": "center" }
      ]
    },
    "content": [
      { "text": "December 15, 2024", "alignment": "right" },
      { "text": "" },
      { "text": "Dear Valued Customer," },
      { "text": "" },
      { "text": "Thank you for your continued business..." },
      { "text": "" },
      { "text": "Sincerely," },
      { "text": "John Smith" },
      { "runs": [{ "text": "CEO", "italic": true }] }
    ],
    "footer": {
      "paragraphs": [
        { "text": "www.acme.com | [email protected]", "alignment": "center" }
      ]
    }
  }]
}

Script Reference

Specification Reference

Paragraph Options

Text Run Options

Table Options

Hyperlink Options

Common Issues and Solutions

Issue: Placeholders not being replaced

Symptoms: Output DOCX still contains {{PLACEHOLDER}} tags.

Solution:

1. Run analyze-template.ts to verify exact tag text
2. Tags may be split across XML runs - the script consolidates these automatically
3. Ensure includeHeaders and includeFooters are true if placeholders are there

Issue: Formatting lost after replacement

Symptoms: Replaced text doesn't match original formatting.

Solution:

• Text replacement preserves the formatting of the original placeholder
• Ensure placeholder is formatted the way you want the final text to appear

Issue: Images not appearing

Symptoms: Image elements are blank in output.

Solution:

1. Use paths relative to the spec.json file location
2. Verify image file exists and is readable
3. Check supported formats: PNG, JPEG, GIF

Issue: Table cell content incorrect

Symptoms: Table cells have wrong content or formatting.

Solution:

• Each cell's content must be an array of paragraph specifications
• Use shading for background color, verticalAlign for alignment

Limitations

• DOCX only: Does not support legacy .doc format
• No track changes: Cannot add or process track changes
• No comments: Cannot add document comments
• No macros: Cannot include VBA macros
• Basic numbering: Limited support for complex numbering schemes
• Text run splitting: Word may split text across XML elements; script handles common cases

Related Skills

• pptx-generator: For creating PowerPoint presentations
• xlsx-generator: For creating Excel spreadsheets
• pdf-generator: For creating PDF documents