export-docx

name	export-docx
description	Convert architecture documents (blueprints, stakeholder presentations) from Markdown to professionally formatted Word (.docx) files. Applies corporate styling, embeds PNG diagrams, and creates presentation-ready documents.

Markdown to Word Exporter

Convert architecture documents to professionally formatted Word documents (.docx) ready for stakeholder presentations, board meetings, and executive approvals.

Perfect for: Executive presentations, board decks, budget approvals, RFPs, investor updates, compliance documentation

---

When to Use This Skill

Use this skill when you need to:

• Share architecture with stakeholders who prefer Word documents
• Present to executives, board members, or finance teams
• Submit RFPs or proposals to clients/agencies
• Create formal documentation for compliance or audits
• Generate printable architecture documents
• Integrate with corporate document management systems

Input: Markdown file (blueprint or stakeholder presentation) Output: Professionally formatted .docx file

---

Supported Document Types

1. Stakeholder Presentations

Input: stakeholder-presentation.md (from the stakeholder presentation workflow) Output: stakeholder-presentation.docx

Formatting:

• Professional cover page with title, date, version
• Table of contents with page numbers
• Section headings with corporate styling
• Embedded PNG diagrams (from diagrams/ folder)
• Tables with alternating row colors
• Approval checklist with signature fields
• Page numbers and headers/footers

2. Full Architecture Blueprints

Input: blueprint.md (from /architect:blueprint) Output: architecture-blueprint.docx

Formatting:

• All 19 sections with proper hierarchy
• Syntax-highlighted code blocks
• Embedded diagrams
• Cross-references between sections
• Appendices with glossary and references

3. Sprint Backlogs

Input: Sprint backlog section or standalone sprint doc Output: sprint-backlog.docx

Formatting:

• User stories as numbered lists
• Acceptance criteria as checkboxes
• Sprint timeline as table
• Priority indicators (High/Medium/Low with colors)

---

How It Works

Step 1: Detect Input Document Type

Analyze markdown to determine document type:

• Contains "Executive Summary" + "Approval Checklist" → Stakeholder presentation
• Contains 19 sections + "Architecture Assumptions" → Full blueprint
• Contains "Sprint X" + "User Stories" → Sprint backlog

Step 2: Convert Markdown to DOCX

Use Pandoc (preferred) or markdown-to-docx library:

Option A: Pandoc (Recommended)

pandoc stakeholder-presentation.md \
  -o stakeholder-presentation.docx \
  --reference-doc=template.docx \
  --toc \
  --toc-depth=3 \
  --number-sections \
  --highlight-style=tango

Pandoc features:

• Table of contents with page numbers
• Section numbering
• Syntax highlighting for code blocks
• Custom styling via reference template
• Image embedding
• Table formatting

Option B: markdown-to-docx (Fallback)

If Pandoc not available, use Node.js library:

npm install markdown-to-docx

# Convert with basic styling
markdown-to-docx --input stakeholder-presentation.md \
                 --output stakeholder-presentation.docx \
                 --style professional

Step 3: Apply Corporate Styling

Use reference template (template.docx) with:

Typography

• Headings: Calibri Bold
  • H1: 20pt, Dark Blue (#1F4E78)
  • H2: 16pt, Dark Blue (#1F4E78)
  • H3: 14pt, Dark Gray (#333333)
• Body text: Calibri 11pt, Black (#000000)
• Code: Consolas 10pt, Gray background (#F5F5F5)

Colors

• Success/Recommended: Green (#28A745) - for ✅ checkmarks
• Warning/Risk: Orange (#FFA500) - for ⚠️ warnings
• Error/High Risk: Red (#DC3545) - for ❌ items
• Info: Blue (#007BFF) - for ℹ️ notes

Page Layout

• Margins: 1 inch all sides
• Page size: Letter (8.5" × 11") or A4
• Orientation: Portrait
• Header: Document title + date (top right)
• Footer: Page numbers (bottom center) + "Confidential" (bottom left)

Tables

• Header row: Dark blue background (#1F4E78), white text, bold
• Alternating rows: White and light gray (#F9F9F9)
• Borders: 1pt solid gray (#CCCCCC)
• Cell padding: 8pt

Images/Diagrams

• Alignment: Center
• Width: 90% of page width (max 6 inches)
• Caption: Below image, 10pt italic, centered
• Spacing: 12pt before and after

Step 4: Embed PNG Diagrams

Replace markdown image references with embedded PNGs:

Markdown:

![Architecture Diagram](./diagrams/architecture-container.png)
*System components and how they connect*

DOCX conversion:

• Embed diagrams/architecture-container.png as inline image
• Resize to 6 inches wide (maintain aspect ratio)
• Add caption "Figure 1: System components and how they connect"
• Center-align

Auto-numbering: Figures numbered sequentially (Figure 1, Figure 2, etc.)

Step 5: Format Special Elements

Checkboxes (Approval Checklist)

Markdown:

- [ ] Budget approved
- [x] Timeline approved

DOCX:

• Unchecked: ☐ Budget approved
• Checked: ☑ Timeline approved
• Use checkbox form fields for interactive PDFs

Tables

Markdown:

| Component | Cost |
|-----------|------|
| Frontend  | $20  |

DOCX:

• Apply table style with header row formatting
• Align numbers right, text left
• Add borders and alternating row colors

Code Blocks

Markdown:

```bash
npm install
```

DOCX:

• Monospace font (Consolas 10pt)
• Light gray background (#F5F5F5)
• 1pt border
• Syntax highlighting if Pandoc used

Callouts/Admonitions

Markdown:

> **Note**: Start with managed platforms, upgrade to AWS when >100K users.

DOCX:

• Light blue background (#E7F3FF)
• Blue left border (4pt, #007BFF)
• Italic text
• "Note:" in bold

Step 6: Add Cover Page

For stakeholder presentations, generate professional cover page:

═══════════════════════════════════════════════════════

              [PROJECT NAME]
        Architecture & Implementation Plan

───────────────────────────────────────────────────────

Prepared for:    [Stakeholder Name/Team]
Prepared by:     Architect AI
Date:            [Generation Date]
Version:         1.0

[Optional: Company Logo]

═══════════════════════════════════════════════════════

Styling:

• Center-aligned
• Project name: 24pt bold, dark blue
• Subtitle: 16pt regular, gray
• Metadata: 11pt, left-aligned in centered block
• Full-page layout (no header/footer)

Step 7: Add Table of Contents

Generate TOC with:

• All H2 and H3 headings
• Page numbers (right-aligned with dot leaders)
• Clickable links (in digital version)
• Max 3 levels deep

Example:

Table of Contents

Executive Summary................................................1
Solution Overview................................................3
  High-Level Architecture Diagram................................3
  Solution Components............................................4
  Key Capabilities...............................................5
Technology Stack & Decisions.....................................6
  Decision 1: Database - PostgreSQL..............................6
  Decision 2: Hosting - Managed Platforms........................7
Cost Breakdown...................................................9
  Infrastructure Costs..........................................9
  Development Costs.............................................10
[...]

Step 8: Add Approval Section

For stakeholder presentations, format approval section as form:

═══════════════════════════════════════════════════════
                   APPROVAL SECTION
═══════════════════════════════════════════════════════

Budget Approved:         ☐ Yes   ☐ No

Timeline Approved:       ☐ Yes   ☐ No

Technical Approach:      ☐ Yes   ☐ No

Risk Mitigation:         ☐ Yes   ☐ No

───────────────────────────────────────────────────────

Decision Required By: ____________________

Approved By: __________________________  Date: _________

Title: _________________________________________________

Signature: ____________________________________________

───────────────────────────────────────────────────────

---

Output Format

When invoked, generate:

📄 Converting markdown to Word document...

✅ Detected document type: Stakeholder Presentation
✅ Parsed markdown structure (11 sections, 47 pages)
✅ Embedded 6 PNG diagrams from diagrams/ folder
✅ Applied corporate styling (Calibri, professional theme)
✅ Generated table of contents (3 levels, 28 entries)
✅ Formatted 8 tables with headers and alternating rows
✅ Added cover page with metadata
✅ Added approval section with signature fields

📄 stakeholder-presentation.docx created (2.4 MB, 47 pages)

Ready for stakeholder review!

Next steps:
- Review document in Microsoft Word or Google Docs
- Customize cover page with company logo
- Adjust approval checklist if needed
- Export to PDF for distribution: File → Export → PDF

---

Customization Options

Optional parameters (ask user if they want to customize):

1. Company logo: Upload logo for cover page (PNG/SVG, max 200px height)
2. Color scheme: Default (blue), Corporate (gray), Custom (specify hex codes)
3. Page size: Letter (default), A4, Legal
4. Font: Calibri (default), Arial, Times New Roman
5. Confidentiality level: Confidential (default), Internal Use Only, Public
6. Version number: 1.0 (default), custom

Default behavior: Blue color scheme, Letter size, Calibri font, "Confidential" footer, version 1.0.

---

Export Options

Option 1: DOCX only

Use this skill to convert `stakeholder-presentation.md` to `stakeholder-presentation.docx`.

Option 2: DOCX + PDF

Use this skill with PDF export enabled.
# → stakeholder-presentation.docx
# → stakeholder-presentation.pdf

Option 3: Custom styling

Use this skill with custom branding options such as logo, color theme, and A4 sizing.
# → stakeholder-presentation.docx (A4, corporate colors, with logo)

---

Technical Implementation

Pandoc Conversion Command

#!/bin/bash
# Convert markdown to DOCX with full styling

INPUT="stakeholder-presentation.md"
OUTPUT="stakeholder-presentation.docx"
TEMPLATE="template.docx"  # Reference template with corporate styling

# Create reference template if it doesn't exist
if [ ! -f "$TEMPLATE" ]; then
  pandoc --print-default-data-file reference.docx > "$TEMPLATE"
  # Customize template.docx with corporate styling
fi

# Convert with Pandoc
pandoc "$INPUT" \
  -o "$OUTPUT" \
  --reference-doc="$TEMPLATE" \
  --toc \
  --toc-depth=3 \
  --number-sections \
  --highlight-style=tango \
  --resource-path=".:diagrams" \
  --metadata title="Architecture & Implementation Plan" \
  --metadata author="Architect AI" \
  --metadata date="$(date +%Y-%m-%d)"

echo "✅ Created $OUTPUT"

Reference Template Creation

# Generate default template
pandoc --print-default-data-file reference.docx > template.docx

# Customize template.docx:
# 1. Open in Microsoft Word
# 2. Modify styles (Heading 1, Heading 2, Normal, etc.)
# 3. Set page layout (margins, headers, footers)
# 4. Configure table styles
# 5. Save and close

# Template is now ready for repeated use

PDF Export (if requested)

# Option A: Use LibreOffice (headless)
libreoffice --headless \
            --convert-to pdf \
            stakeholder-presentation.docx \
            --outdir .

# Option B: Use Pandoc with LaTeX
pandoc stakeholder-presentation.md \
  -o stakeholder-presentation.pdf \
  --pdf-engine=xelatex \
  --toc \
  --number-sections

---

Error Handling

If Pandoc not installed:

• Action: Fallback to markdown-to-docx library
• Notify user: "ℹ️ Using basic conversion (Pandoc not found). Install Pandoc for better formatting."
• Install prompt: "Run: brew install pandoc (Mac) or apt install pandoc (Linux)"

If diagrams/ folder missing:

• Action: Continue conversion, skip image embedding
• Notify user: "⚠️ diagrams/ folder not found. Run /architect:export-diagrams first for embedded images."

If reference template missing:

• Action: Generate default template on-the-fly
• Notify user: "ℹ️ Using default styling. Customize template.docx for corporate branding."

If input markdown not found:

• Action: Error with guidance
• Example: "❌ stakeholder-presentation.md not found. Generate the stakeholder presentation markdown first."

---

Integration with Other Skills

Recommended workflow:

# 1. Generate blueprint
/architect:blueprint

# 2. Create stakeholder presentation markdown
# 3. Export diagrams to PNG
/architect:export-diagrams

# 4. Use this skill to convert the markdown to DOCX

# Result: stakeholder-presentation.docx ready for executives

---

Success Criteria

A successful DOCX export should:

• ✅ Preserve all markdown content (no data loss)
• ✅ Apply professional corporate styling
• ✅ Embed all PNG diagrams at appropriate sizes
• ✅ Generate table of contents with page numbers
• ✅ Format tables with headers and alternating rows
• ✅ Add cover page with metadata
• ✅ Add headers/footers with page numbers
• ✅ Include approval section with signature fields
• ✅ Be editable in Microsoft Word or Google Docs
• ✅ Be print-ready (proper margins, page breaks)

---

Files Created

stakeholder-presentation.docx        # Main output (2-5 MB)
stakeholder-presentation.pdf         # Optional PDF export
template.docx                        # Reference template (reusable)

File sizes:

• DOCX: 2-5 MB (with embedded diagrams)
• PDF: 1-3 MB (compressed diagrams)
• Template: 50-100 KB

---

Advanced Features

Custom Branding

Replace default template with corporate template:

# 1. Create corporate template
# - Open template.docx in Word
# - Apply corporate fonts, colors, logo
# - Save as corporate-template.docx

# 2. Use this skill with the custom template during conversion

Batch Export

Export multiple documents at once:

# Export all markdown files in the current directory with this skill's batch workflow
# Output:
# ✅ blueprint.docx
# ✅ stakeholder-presentation.docx
# ✅ sprint-backlog.docx

Version Control

Automatically version documents:

Use this skill with document version `2.1`.
# Output: stakeholder-presentation-v2.1.docx
# Footer: "Version 2.1 - Generated 2026-02-07"

---

Examples

Example 1: Basic Stakeholder Doc Export

Use this skill on `stakeholder-presentation.md`.
# Output:
# ✅ stakeholder-presentation.docx created (47 pages, 2.4 MB)

Example 2: With Company Logo and PDF

Use this skill with a logo and PDF export enabled.
# Output:
# ✅ stakeholder-presentation.docx (with Acme logo)
# ✅ stakeholder-presentation.pdf

Example 3: Full Blueprint Export

Use this skill on `blueprint.md` with output path `architecture-blueprint.docx`.
# Output:
# ✅ architecture-blueprint.docx (19 sections, 87 pages)

---

Quality Assurance

Before considering export complete, verify:

• All sections from markdown are present in DOCX
• All diagrams are embedded and visible
• Table of contents has correct page numbers
• Tables are formatted with headers
• Code blocks use monospace font
• Cover page has correct metadata
• Approval section has signature fields
• Headers/footers are present on all pages (except cover)
• Page numbers start from correct page
• Document is editable without errors
• File size is reasonable (<10 MB)

---

Troubleshooting

Problem: Images are too large/small

Solution: Adjust max-width in Pandoc:

pandoc ... --metadata max-width=6in

Problem: Table of contents missing

Solution: Ensure --toc flag is used and H2/H3 headings exist

Problem: Code blocks lose formatting

Solution: Use --highlight-style=tango and monospace font in template

Problem: PDF export fails

Solution: Install required LaTeX packages or use LibreOffice conversion

Problem: Special characters corrupted

Solution: Ensure UTF-8 encoding:

pandoc ... --metadata charset=utf-8