# Edgemint

> 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.

- Skill: `raphaelmansuy/edgemint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add raphaelmansuy/edgemint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/raphaelmansuy/edgemint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: raphaelmansuy (https://skillmd.com/u/raphaelmansuy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/raphaelmansuy/edgemint

---


# 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:

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

If `NOT_INSTALLED`:

```bash
pip install "edgemint[pandoc]"
```

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

```bash
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:

```bash
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`:**

```markdown
# 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
```

```markdown
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```markdown
:::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:

```markdown
|:---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:

```markdown
:::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|bottom"}` | Vertical alignment of this cell |
| `[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

```markdown
:::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:

```bash
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.