Docx Format Replicator

DOCX Format Replicator

Overview

Extract formatting information from existing Word documents (.docx) and use it to generate new documents with identical formatting but different content. This skill enables creating document templates, maintaining consistent formatting across multiple documents, and replicating complex Word document structures.

When to Use This Skill

Use this skill when the user:

• Wants to extract formatting from an existing Word document
• Needs to create multiple documents with the same format
• Has a template document and wants to generate similar documents with new content
• Asks to "replicate", "copy format", "use the same style", or "create a document like"
• Mentions document templates, corporate standards, or format consistency

Workflow

Step 1: Extract Format from Template

Extract formatting information from an existing Word document to create a reusable format configuration.

python scripts/extract_format.py <template.docx> <output.json>

Example:

python scripts/extract_format.py "HY研制任务书.docx" format_template.json

What Gets Extracted:

• Style definitions (fonts, sizes, colors, alignment)
• Paragraph and character styles
• Numbering schemes (1, 1.1, 1.1.1, etc.)
• Table structures and styles
• Header and footer configurations

Output: JSON file containing all format information (see references/format_config_schema.md for details)

Step 2: Prepare Content Data

Create a JSON file with the actual content for the new document. The content must follow the structure defined in references/content_data_schema.md.

Content Structure:

{
  "metadata": {
    "title": "Document Title",
    "author": "Author Name",
    "version": "1.0",
    "date": "2025-01-15"
  },
  "sections": [
    {
      "type": "heading",
      "content": "Section Title",
      "level": 1,
      "number": "1"
    },
    {
      "type": "paragraph",
      "content": "Paragraph text content."
    },
    {
      "type": "table",
      "rows": 3,
      "cells": [
        ["Header 1", "Header 2"],
        ["Data 1", "Data 2"]
      ]
    }
  ]
}

Supported Section Types:

• heading - Headings with optional numbering
• paragraph - Text paragraphs
• table - Tables with configurable rows and columns
• page_break - Page breaks

See assets/example_content.json for a complete example.

Step 3: Generate New Document

Generate a new Word document using the extracted format and prepared content.

python scripts/generate_document.py <format.json> <content.json> <output.docx>

Example:

python scripts/generate_document.py format_template.json new_content.json output_document.docx

Result: A new .docx file with the format from the template applied to the new content.

Complete Example Workflow

User asks: "I have a research task document. I need to create 5 more documents with the same format but different content."

1. Extract the format:

python scripts/extract_format.py research_task_template.docx template_format.json

2. Create content files for each new document (content1.json, content2.json, etc.)

3. Generate documents:

python scripts/generate_document.py template_format.json content1.json document1.docx
python scripts/generate_document.py template_format.json content2.json document2.docx
# ... repeat for all documents

Common Use Cases

Corporate Document Templates

Extract format from a company template and generate reports, proposals, or specifications with consistent branding.

# One-time: Extract company template
python scripts/extract_format.py "Company Template.docx" company_format.json

# For each new document:
python scripts/generate_document.py company_format.json new_report.json "Monthly Report.docx"

Technical Documentation Series

Create multiple technical documents (specifications, test plans, manuals) with identical formatting.

# Extract from specification template
python scripts/extract_format.py spec_template.docx spec_format.json

# Generate multiple specs
python scripts/generate_document.py spec_format.json product_a_spec.json "Product A Spec.docx"
python scripts/generate_document.py spec_format.json product_b_spec.json "Product B Spec.docx"

Research Task Documents

The included example template (assets/hy_template_format.json) demonstrates a complete research task document format with:

• Approval/review table in header
• Multi-level numbering (1, 1.1, 1.1.1)
• Technical specification tables
• Structured sections

Use this as a starting point for similar technical documents.

Advanced Usage

Customizing Extraction

Modify scripts/extract_format.py to extract additional properties not covered by default:

• Custom XML elements
• Advanced table features (merged cells, borders)
• Embedded objects
• Custom properties

Extending Content Types

Add new section types in scripts/generate_document.py:

• Images with captions
• Bulleted or numbered lists
• Footnotes and endnotes
• Custom content blocks

See references/content_data_schema.md for extension guidelines.

Batch Processing

Create a wrapper script to generate multiple documents:

import json
import subprocess

format_file = "template_format.json"
content_files = ["content1.json", "content2.json", "content3.json"]

for i, content_file in enumerate(content_files, 1):
    output = f"document_{i}.docx"
    subprocess.run([
        "python", "scripts/generate_document.py",
        format_file, content_file, output
    ])

Dependencies

The scripts require:

• Python 3.7+
• python-docx library: pip install python-docx

No additional dependencies are needed for the core functionality.

Resources

scripts/

• extract_format.py - Extract formatting from Word documents
• generate_document.py - Generate new documents from format + content

Both scripts include built-in help:

python scripts/extract_format.py --help
python scripts/generate_document.py --help

references/

• format_config_schema.md - Complete schema for format configuration files
• content_data_schema.md - Complete schema for content data files

Read these for detailed information on file structures and available options.

assets/

• hy_template_format.json - Example extracted format from a technical research task document
• example_content.json - Example content data showing all section types

Use these as references when creating your own format and content files.

Troubleshooting

Missing styles in output: Ensure style IDs in content data match those in format config. Check format.json for available style IDs.

Table formatting issues: Verify table dimensions (rows/columns) match between content data and format config. See format_config_schema.md for table structure.

Font not displaying correctly: Some fonts may not be available on all systems. Check that referenced fonts are installed.

Dependencies missing: Install required Python packages:

pip install python-docx

Tips

1. Test with examples first: Use the included hy_template_format.json and example_content.json to understand the workflow before extracting your own formats.

2. Start simple: Begin with basic headings and paragraphs, then add tables and complex formatting.

3. Validate JSON: Use a JSON validator to check content data files before generating documents.

4. Keep format configs: Store extracted format configurations for reuse across multiple projects.

5. Version control: Track both format configs and content data in version control for reproducible document generation.

Content Data Schema

This document describes the JSON schema for content data files used by generate_document.py.

Overview

The content data file defines the actual content (text, headings, tables) that will be placed into a Word document using the formatting rules from a format configuration.

Schema Structure

{
  "metadata": {},
  "sections": []
}

Fields

metadata

Type: object Description: Optional metadata about the document content.

Fields:

• title (string): Document title
• author (string): Document author
• version (string): Version number
• date (string): Document date

Example:

"metadata": {
  "title": "Product Research Task Specification",
  "author": "Engineering Team",
  "version": "1.0",
  "date": "2025-01-15"
}

sections

Type: array Description: Array of content sections that make up the document. Sections are processed in order.

Each section is an object with a type field and type-specific properties.

Section Types

Heading Section

Create a heading with optional numbering.

Fields:

• type (string): Must be "heading"
• content (string): Heading text
• level (number): Heading level (1-9)
• number (string, optional): Numbering prefix (e.g., "1", "1.1", "1.1.1")

Example:

{
  "type": "heading",
  "content": "Introduction",
  "level": 1,
  "number": "1"
}

Paragraph Section

Create a text paragraph.

Fields:

• type (string): Must be "paragraph"
• content (string): Paragraph text
• style_id (string, optional): Style ID to apply from format config

Example:

{
  "type": "paragraph",
  "content": "This document outlines the technical requirements for the product.",
  "style_id": "1"
}

Table Section

Create a table.

Fields:

• type (string): Must be "table"
• rows (number): Number of rows
• columns (array): Column width definitions (from format config)
• table_index (number, optional): Index of table config to use
• cells (array): 2D array of cell contents

Example:

{
  "type": "table",
  "rows": 3,
  "columns": ["2000", "8000"],
  "table_index": 0,
  "cells": [
    ["Header 1", "Header 2"],
    ["Row 1 Col 1", "Row 1 Col 2"],
    ["Row 2 Col 1", "Row 2 Col 2"]
  ]
}

Page Break Section

Insert a page break.

Fields:

• type (string): Must be "page_break"

Example:

{
  "type": "page_break"
}

Complete Example

Here's a complete content data file for a technical document:

{
  "metadata": {
    "title": "New Product Research Task Specification",
    "author": "Research Team",
    "version": "1.0",
    "date": "2025-01-15"
  },
  "sections": [
    {
      "type": "heading",
      "content": "Introduction",
      "level": 1,
      "number": "1"
    },
    {
      "type": "paragraph",
      "content": "This document defines the research and development tasks for the new product initiative."
    },
    {
      "type": "heading",
      "content": "Product Name and Code",
      "level": 1,
      "number": "2"
    },
    {
      "type": "paragraph",
      "content": "Product Name: Advanced Control System"
    },
    {
      "type": "paragraph",
      "content": "Product Code: ACS-2025-01"
    },
    {
      "type": "heading",
      "content": "Technical Specifications",
      "level": 1,
      "number": "3"
    },
    {
      "type": "heading",
      "content": "Electrical Requirements",
      "level": 2,
      "number": "3.1"
    },
    {
      "type": "table",
      "rows": 4,
      "columns": ["3000", "7000"],
      "cells": [
        ["Parameter", "Specification"],
        ["Input Voltage", "220V AC ± 10%"],
        ["Power Consumption", "≤ 500W"],
        ["Frequency", "50Hz ± 2Hz"]
      ]
    },
    {
      "type": "page_break"
    },
    {
      "type": "heading",
      "content": "Testing Requirements",
      "level": 1,
      "number": "4"
    },
    {
      "type": "paragraph",
      "content": "All products must undergo comprehensive testing according to industry standards."
    }
  ]
}

Usage Patterns

Multi-level Numbering

For documents with nested sections (1, 1.1, 1.1.1):

[
  {"type": "heading", "content": "First Section", "level": 1, "number": "1"},
  {"type": "heading", "content": "Subsection A", "level": 2, "number": "1.1"},
  {"type": "heading", "content": "Sub-subsection", "level": 3, "number": "1.1.1"},
  {"type": "heading", "content": "Subsection B", "level": 2, "number": "1.2"},
  {"type": "heading", "content": "Second Section", "level": 1, "number": "2"}
]

Complex Tables

For tables with merged cells or special formatting, you may need to extend the schema:

{
  "type": "table",
  "rows": 3,
  "columns": ["2000", "4000", "4000"],
  "cells": [
    ["Header 1", "Header 2", "Header 3"],
    ["Data 1", "Data 2", "Data 3"],
    ["Data 4", "Data 5", "Data 6"]
  ],
  "merge_cells": [
    {"row": 0, "col": 1, "row_span": 1, "col_span": 2}
  ]
}

Approval Tables

For documents with approval/review tables (common in technical documents):

{
  "type": "table",
  "table_index": 0,
  "cells": [
    ["Version", "1.0"],
    ["Author", "John Doe"],
    ["Reviewer", "Jane Smith"],
    ["Approver", "Manager Name"],
    ["Date", "2025-01-15"]
  ]
}

Tips

1. Consistent Numbering: Ensure numbering is sequential and follows the document hierarchy 2. Style IDs: Reference style IDs from the format configuration to maintain consistency 3. Table Index: Use the same table_index for tables that should have the same formatting 4. Empty Paragraphs: Use empty content strings for spacing: {"type": "paragraph", "content": ""} 5. Special Characters: Properly escape JSON special characters in content strings

Extending the Schema

To support additional content types:

1. Define a new section type 2. Add handling in generate_document.py 3. Document the new type in this file 4. Provide examples

Common extensions:

• Images ({"type": "image", "path": "...", "width": "..."})
• Lists ({"type": "list", "items": [...], "style": "bullet"})
• Footnotes ({"type": "footnote", "content": "..."})

Format Configuration Schema

This document describes the JSON schema for format configuration files generated by extract_format.py.

Overview

The format configuration file stores extracted formatting information from a Word document, including styles, numbering, table structures, and header/footer information.

Schema Structure

{
  "source_document": "string",
  "styles": {},
  "numbering": {},
  "tables": [],
  "headers_footers": {}
}

Fields

source_document

Type: string Description: Name of the source document from which the format was extracted.

Example:

"source_document": "template.docx"

styles

Type: object Description: Dictionary of style definitions, keyed by style ID.

Each style object contains:

• id (string): Style identifier
• name (string): Human-readable style name
• type (string): Style type (paragraph, character, table, numbering)
• fonts (object): Font properties
• ascii (string): ASCII font name
• hAnsi (string): High ANSI font name
• eastAsia (string): East Asian font name
• size (string): Font size in half-points
• paragraph (object): Paragraph properties
• alignment (string): Text alignment (left, center, right, both)
• spacing (object): Line spacing configuration

Example:

"styles": {
  "1": {
    "id": "1",
    "name": "Normal",
    "type": "paragraph",
    "fonts": {
      "ascii": "Times New Roman",
      "hAnsi": "Times New Roman",
      "eastAsia": "宋体",
      "size": "24"
    },
    "paragraph": {
      "alignment": "left",
      "spacing": {
        "line": "360",
        "lineRule": "auto"
      }
    }
  },
  "2": {
    "id": "2",
    "name": "heading 1",
    "type": "paragraph",
    "fonts": {
      "ascii": "Times New Roman",
      "size": "32"
    },
    "paragraph": {
      "alignment": "left"
    }
  }
}

numbering

Type: object Description: Numbering definitions for automatic numbering (1, 1.1, 1.1.1, etc.)

Each numbering entry maps a numbering ID to its abstract numbering definition.

Example:

"numbering": {
  "1": {
    "abstractNumId": "0"
  },
  "2": {
    "abstractNumId": "1"
  }
}

tables

Type: array Description: Array of table structure definitions found in the document.

Each table object contains:

• index (number): Zero-based index of the table
• rows (number): Number of rows in the table
• columns (array): Array of column widths
• properties (object): Table properties
• width (object): Table width settings
• style (string): Table style ID

Example:

"tables": [
  {
    "index": 0,
    "rows": 5,
    "columns": ["1984", "8076", "40"],
    "properties": {
      "width": {
        "value": "10100",
        "type": "dxa"
      },
      "style": "49"
    }
  }
]

headers_footers

Type: object Description: Information about headers and footers in the document.

Contains:

• headers (array): List of header files
• footers (array): List of footer files

Example:

"headers_footers": {
  "headers": [
    {
      "file": "word/header1.xml",
      "exists": true
    }
  ],
  "footers": [
    {
      "file": "word/footer1.xml",
      "exists": true
    }
  ]
}

Usage Notes

Style IDs vs Style Names

Word documents use numeric style IDs internally (e.g., "1", "2") which map to named styles (e.g., "Normal", "heading 1"). The format configuration preserves both for maximum compatibility.

Width Units

Widths in OOXML use "dxa" units (twentieths of a point). Common conversions:

• 1 inch = 1440 dxa
• 1 cm = 567 dxa
• 1 pt = 20 dxa

Extracting Additional Properties

The current schema covers the most common formatting properties. For specialized documents, you may need to:

1. Modify extract_format.py to extract additional properties 2. Update this schema documentation accordingly 3. Update generate_document.py to apply those properties

Example Complete Configuration

{
  "source_document": "research_task_template.docx",
  "styles": {
    "1": {
      "id": "1",
      "name": "Normal",
      "type": "paragraph",
      "fonts": {
        "ascii": "Times New Roman",
        "hAnsi": "Times New Roman",
        "eastAsia": "宋体",
        "size": "24"
      },
      "paragraph": {
        "alignment": "left"
      }
    }
  },
  "numbering": {
    "1": {
      "abstractNumId": "0"
    }
  },
  "tables": [
    {
      "index": 0,
      "rows": 8,
      "columns": ["2000", "8000"],
      "properties": {
        "width": {
          "value": "10000",
          "type": "dxa"
        },
        "style": "GridTable"
      }
    }
  ],
  "headers_footers": {
    "headers": [
      {"file": "word/header1.xml", "exists": true}
    ],
    "footers": [
      {"file": "word/footer1.xml", "exists": true}
    ]
  }
}