# 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-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add raphaelmansuy/edgemint-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/raphaelmansuy/edgemint-2/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-2

---


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

---

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