edgemint

name	edgemint
description	Generate style-faithful DOCX documents from Markdown using the edgemint CLI. Use this skill when the user wants to: create a branded Word document from Markdown or AsciiDoc, extract visual styles from a .docx template, regenerate a document after editing its content, diff two style sheets, audit a template change, or automate a batch document pipeline. Handles all edgemint commands: extract-styles, extract, apply-styles, diff, validate, info, schema.
argument-hint	[template.docx] [action: extract|apply|diff|batch|inspect]
allowed-tools	Bash(edgemint *) Bash(pip install *) Bash(pandoc *) Read Write
effort	high

edgemint — DOCX Style Extraction & Document Generation

You are an expert at producing style-faithful Word documents from Markdown source using the edgemint CLI. You understand DOCX named styles, Pandoc Extended Markdown custom-style annotations, and the three-file architecture (content.md + styles.json + media/).

---

0. Prerequisites Check

Before any operation, verify edgemint is installed:

edgemint --version 2>/dev/null || echo "NOT_INSTALLED"

If NOT_INSTALLED:

pip install "edgemint[pandoc]"

Pandoc is required for extract and apply-styles. Confirm:

pandoc --version 2>/dev/null | head -1 || echo "PANDOC_MISSING"

---

1. Core Concept

edgemint separates what a document looks like from what it says:

  template.docx  ──extract-styles──►  styles.json   (visual identity)
  content.md     ──apply-styles ──►   output.docx   (content + identity = output)

styles.json is the portable visual identity. Check it into version control. content.md is plain Pandoc Extended Markdown. Edit it freely.

---

2. Workflows

Workflow A — Extract styles from a template

When the user has a .docx template and wants to understand or capture its styles:

edgemint extract-styles template.docx -o styles.json --resolved

Then read styles.json and summarise:

• Total style count by type (paragraph / character / table)
• Key custom styles (non-built-in, branded names)
• Theme fonts (headings vs. body)
• Color palette from theme

Present a table: name | type | font | size_pt | color.

---

Workflow B — Generate a styled document

When the user wants to produce a branded .docx from Markdown content:

1. If no styles.json exists yet, run Workflow A first.
2. Read styles.json — note every available name value precisely.
3. Write content.md using Pandoc Extended Markdown and custom-style annotations.
4. Run edgemint apply-styles content.md styles.json -o output.docx.
5. Confirm the output file exists and report its byte size.

Writing rules for content.md:

# Standard Markdown → auto-mapped to DOCX built-in styles

# Heading 1          → Heading 1
## Heading 2         → Heading 2

Normal paragraph text → Normal / Body Text

**bold**             → Strong character style
*italic*             → Emphasis character style
- Bullet item        → List Bullet
1. Numbered item     → List Number
> Blockquote         → Quote
$E = mc^2$           → OMML equation (Pandoc converts LaTeX)
![Cap](media/x.png)  → embedded image with media-dir lookup

# Named / branded styles → use custom-style annotations

::: {custom-style="Heading 1"}
Chapter Title
:::

::: {custom-style="Body Text"}
Paragraph content.
:::

The project is [on track]{custom-style="Status Green"}.

Rules:

1. Always use the exact name from styles.json — never guess or invent names.
2. Prefer standard Markdown over custom-style when the auto-mapping is equivalent.
3. Math: $...$ inline, $$...$$ display — Pandoc converts to OMML automatically.
4. Images: ![Caption](media/file.png){width=80%} — pass --media dir to apply-styles.
5. Page breaks: raw OOXML fence:

   ```{=openxml}
   <w:p><w:r><w:br w:type="page"/></w:r></w:p>
   ```
   

---

Workflow C — Full round-trip extraction

When the user wants to decompose an existing .docx into editable source:

edgemint extract document.docx -o project/

Produces:

project/
  content.md    ← Pandoc Extended Markdown (all content)
  styles.json   ← complete visual identity
  media/        ← all embedded images, extracted

Explain the structure, then tell the user how to re-generate:

edgemint apply-styles project/content.md project/styles.json \
  -o rebuilt.docx --media project/media

---

Workflow D — Diff / audit styles

When the user wants to compare two templates or detect brand changes:

edgemint extract-styles old-template.docx -o before.json
edgemint extract-styles new-template.docx -o after.json
edgemint diff before.json after.json

Present the diff grouped by: Added, Removed, Modified (with exact property changes).

---

Workflow E — Batch document generation

When the user wants to generate multiple documents from one template:

edgemint extract-styles template.docx -o styles.json  # once

for md in docs/*.md; do
  name=$(basename "$md" .md)
  edgemint apply-styles "$md" styles.json -o "output/${name}.docx"
done

Write each .md file with proper custom-style annotations before running the loop. Show the user the file count and total output size when done.

---

Workflow F — Quick inspection

edgemint info document.docx

Summarise: style count, key custom styles, paragraph vs. character split.

---

Workflow G — Enhanced table formatting

edgemint supports a rich :::table fence that goes far beyond standard pipe tables. Use it whenever the user needs: table styles, caption, alignment, column widths, row backgrounds / heights / repeat-header, cell spanning, or cell vertical alignment.

Syntax overview

:::table {style="TableGrid" caption="Table 1. Results" align="center" width="80%"}
| Column A       | Column B       | Column C       | {repeat}
|:---w:40%       |:---w:30%       |:---w:30%       |
| Cell           | [Highlight]{bg="#FFFF00"} | >> |
| [Top]{va="top"}| Value          | ^^             | {bg="#F2F2F2" height="20pt"}
:::

Fence attributes (:::table {…})

Attribute	Values	Description
style	style-id string	Named DOCX table style (must exist in styles.json)
caption	string	Caption paragraph placed above the table
align	left center right	Table horizontal alignment
width	80% or 360pt	Table width (pct = % of body; pt = absolute)
no-header	flag	Tables start with a data row, not a header row

Separator row — column widths

The separator row (pipes + dashes) can carry per-column width tokens:

|:---w:40%|:---w:30%|---|

• :---w:40% — set this column to 40 % of the table body width
• :---w:360pt — absolute width in points
• --- (no w:) — auto-distribute the remaining space equally

Column alignment (:---, ---:, :---:) is also supported in the same token.

Row trailing attributes ({…})

Append {…} at the end of a row to set row-level properties:

Attribute	Effect
repeat	Mark row as repeating header (w:tblHeader)
no-split	Prevent row from breaking across pages (w:cantSplit)
height="20pt"	Exact row height (twips = pt × 20)
height="at-least:20pt"	Minimum row height
bg="#RRGGBB"	Row background shading

Cell merging

Syntax	Meaning
>>	Horizontal merge — this cell is absorbed by the cell to its left
^^	Vertical merge — this cell is a continuation of the cell above

Example — 2-column span + 2-row span:

:::table {}
| Merged across two cols | >>  |
|------------------------|-----|
| Tall                   | A   |
| ^^                     | B   |
:::

Inline cell spans [text]{attr}

Inside any cell you can span over inline ranges:

Syntax	Effect
[text]{bg="#RRGGBB"}	Cell background shading (Level 4)
`[text]{va="top	center
[text]{custom-style="Emphasis"}	Character style run

Using {bg=…} or {va=…} on ANY inline in the cell sets the corresponding w:tcPr/w:shd or w:tcPr/w:vAlign for the entire cell.

Complete self-contained example

:::table {caption="Q1 Performance" style="TableGrid" align="center" width="90%"}
| Product        | Q1 Sales | Change | {repeat}
|:---w:40%       |:---w:30% |:---w:30%|
| Alpha          | 1 000    | +5 %   |
| Beta           | [2 500]{bg="#E2EFDA"} | >> | {bg="#F5F5F5"}
| Gamma          | ^^       | -3 %   |
| **Total**      | 3 500    | +1 %   | {height="at-least:24pt" no-split}
:::

When to use :::table vs. plain pipe tables

Need	Choice
Simple data, no decoration	Plain pipe table
Named style, caption, alignment	:::table {style=… caption=…}
Column widths, row heights/BGs	:::table with w: tokens + row attrs
Cell spanning (colspan / rowspan)	:::table with >> / ^^
Complex cell-level bg or vAlign	:::table with […]{bg=… va=…}

---

3. Error Handling

Exit code	Meaning	Action
0	Success	Continue
1	Usage error	Show correct usage
2	File not found / invalid	Check path, check it's a valid DOCX
3	Schema / validation error	Run edgemint validate styles.json
4	Pandoc error	Run pandoc --version; install edgemint[pandoc] if missing
5	Security error	Warn user — file failed ZIP bomb / path traversal check

Warnings about "style deduplication" and "list style" are normal — edgemint auto-fixes both (Pandoc bugs #7280 / #8350). Do not flag them to the user.

---

4. Output Confirmation

After every apply-styles call:

ls -lh output.docx

Report: ✓ output.docx (42 KB) or the equivalent.

---

5. Principles

• Never modify styles.json manually — always re-extract from the source .docx.
• Never invent style names — only use names that appear in styles.json.
• The three-file architecture (content.md + styles.json + media/) maps to a natural Git repo layout: content and identity evolve independently.
• When in doubt, run edgemint validate styles.json before generating.