edgemint 1.3.0

DOCX style extraction and regeneration CLI

edgemint

Extract the visual identity from any Word template. Regenerate pixel-perfect branded documents from Markdown. Every time. In seconds.

---

Why does this exist?

You have a beautiful .docx template. Corporate fonts, precise spacing, branded headings. Your designer spent weeks on it.

Now you need to produce 50 reports with that exact look — from Markdown your team writes in Git repos, wikis, and notebooks.

What happens today:

  THE PAINFUL WAY
  ───────────────────────────────────────────────────────────────
  1. Open Word
  2. Copy-paste your Markdown content
  3. Manually apply Heading 1... Heading 2... Body Text...
  4. Fix the spacing. Again.
  5. Fix the fonts. Again.
  6. Realize the numbered list is wrong. Fix it. Again.
  7. Repeat for the next 49 documents.

  Total time: hours    Errors: guaranteed    Will to live: declining

What should happen:

  THE edgemint WAY
  ───────────────────────────────────────────────────────────────
  1. Extract styles from your template     (once,  ~1 second)
  2. Write content in Markdown             (the fun part)
  3. Run one command                       (< 5 seconds)
  4. Get a perfectly styled .docx          (every time)

  Total time: seconds    Errors: zero    Will to live: restored

edgemint is a CLI that extracts the complete visual identity from any .docx template into a portable JSON file, then regenerates new documents from Markdown or AsciiDoc while preserving every font, color, spacing, and border — losslessly.

---

How it works

  YOUR TEMPLATE          YOUR CONTENT           YOUR OUTPUT
  ─────────────          ────────────           ───────────

  ┌────────────┐          ┌────────────┐         ┌────────────┐
  │ branded    │          │ content.md │         │ branded    │
  │ .docx      │          │ (Markdown) │         │ .docx      │
  └─────┬──────┘          └─────┬──────┘         └────────────┘
        │                       │                      ▲
        │ extract-styles        │                      │
        ▼                       │    apply-styles      │
  ┌────────────┐                └─────────────────────►┘
  │ styles.json│
  │ (identity) │
  └────────────┘

  "what it looks like"   "what it says"     "both, together"

Two commands. Any template. Any content. Every time.

---

Install

# Recommended: install as a CLI tool (works on macOS, Linux, Windows)
pipx install 'edgemint[pandoc]'

# Lightweight (style extraction + diff only, no Pandoc)
pipx install edgemint

# Inside a virtual environment or CI
pip install 'edgemint[pandoc]'

# Docker (zero local dependencies)
docker pull ghcr.io/raphaelmansuy/edgemint:latest

macOS note: pip install is blocked by Homebrew's Python. Use pipx install or activate a virtual environment first.

---

60-second demo

# 1. See what styles are in your template
edgemint info brand.docx

# 2. Extract the visual identity
edgemint extract-styles brand.docx -o styles.json

# 3. Write your content in Markdown, then generate
edgemint apply-styles report.md styles.json -o report.docx

Open report.docx. Every font, color, and spacing is identical to your template.

---

Full round-trip with images

# Extract everything: content + styles + media
edgemint extract source.docx -o project/
# → project/content.md   (Pandoc Extended Markdown)
# → project/styles.json  (complete visual identity)
# → project/media/       (all embedded images)

# Edit project/content.md, then regenerate
edgemint apply-styles project/content.md project/styles.json \
  -o rebuilt.docx --media project/media

---

Commands

edgemint extract-styles   template.docx  -o styles.json
edgemint extract          document.docx  -o project/
edgemint apply-styles     content.md styles.json  -o output.docx
edgemint apply-styles     content.adoc styles.json  -o output.docx --input-format asciidoc
edgemint diff             old.json new.json
edgemint validate         styles.json
edgemint info             template.docx
edgemint schema

Command	Needs Pandoc?	What it does
extract-styles	No	.docx → styles.json
extract	Yes	.docx → content.md + styles.json + media/
apply-styles	Yes	content.md + styles.json → .docx
diff	No	compare two styles.json files
validate	No	check styles.json schema
info	No	quick .docx style summary
schema	No	print the JSON Schema

---

Use in CI/CD

Generate styled documents on every push — no Word needed:

# .github/workflows/generate-docs.yml
jobs:
  generate:
    runs-on: ubuntu-latest
    container: ghcr.io/raphaelmansuy/edgemint:latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          for md in reports/*.md; do
            edgemint apply-styles "$md" brand/styles.json \
              -o "output/$(basename $md .md).docx"
          done
      - uses: actions/upload-artifact@v4
        with:
          name: reports
          path: output/*.docx

Push Markdown → get styled .docx artifacts. Every commit. Automatically.

---

AI Agent Integration

edgemint is designed to be a first-class tool for AI coding agents. When an agent (Claude, GPT-4o, Gemini, Cursor, etc.) needs to produce a formatted Word document, the workflow is:

  AGENT WORKFLOW
  ──────────────────────────────────────────────────────────────────
  User: "Write a Q3 report using our brand template."

  1. Agent reads styles.json  (knows every branded paragraph/char style)
  2. Agent writes content.md  (Markdown + custom-style annotations)
  3. Agent calls edgemint      edgemint apply-styles content.md styles.json -o report.docx
  4. Agent returns report.docx (pixel-perfect branded output)

  No Word. No manual styling. No human in the loop.

This pattern works for:

• Report generation — audit reports, weekly updates, release notes
• Book authoring — Packt, O'Reilly, or any publisher template
• Legal documents — contract templates, NDAs, briefs
• Engineering docs — RFCs, architecture proposals, ADRs
• Batch pipelines — generate 100 branded PDFs from one template in CI

Install the Claude Code Skill

The repo ships two ready-to-use Claude Code skills in .claude/skills/:

Skill	Purpose
edgemint	General DOCX generation for any template
edgemint-packt	Packt publisher house-style specialisation

Install the general skill globally:

mkdir -p ~/.claude/skills/edgemint
cp .claude/skills/edgemint/SKILL.md ~/.claude/skills/edgemint/SKILL.md

Or use it project-locally (Claude Code picks it up automatically):

# already there — just open Claude Code in this repo
ls .claude/skills/

Conversational example

Once the skill is installed, an agent session looks like this:

User:  Extract styles from our brand.docx, then write a two-page
       executive summary about Q3 sales using the template.

Claude: I'll extract the styles first, then write the content.

  $ edgemint extract-styles brand.docx -o styles.json
  ✓ 47 styles extracted

  [writes content.md with correct custom-style annotations]

  $ edgemint apply-styles content.md styles.json -o executive-summary.docx
  ✓ executive-summary.docx (42 KB)

  Done — executive-summary.docx is ready to submit.

---

Audit style changes between template versions

edgemint diff brand-v1.json brand-v2.json

CHANGED  Heading1
  font.size_pt: 16.0 → 18.0
  font.color: #2F5496 → #1A3C6E
ADDED    Subtitle
REMOVED  BodyTextIndent

Version-control your styles.json and review brand changes in PRs.

---

What is preserved

  Paragraph styles    LOSSLESS   custom-style fenced divs
  Character styles    LOSSLESS   custom-style bracketed spans
  Bold / italic       LOSSLESS   standard Markdown syntax
  Footnotes           LOSSLESS   [^id] syntax
  Images              LOSSLESS   ![alt](media/x.png)
  Tables              LOSSLESS   pipe / grid tables
  Math (LaTeX)        LOSSLESS   $...$ and $$...$$
  Theme / colors      LOSSLESS   styles.json sidecar
  Headers / footers   LOSSLESS   styles.json sidecar
  ──────────────────────────────────────────────────────
  Track changes       LOST       accepted only
  Comments            LOST       no Markdown equivalent
  VBA / Macros        LOST       stripped (security)

No surprises. No silent degradation. Losses are always logged as warnings.

---

Development workflow

git clone https://github.com/raphaelmansuy/edgemint
cd edgemint
make bootstrap     # create .venv, install all deps
make doctor        # verify toolchain
make fmt           # auto-format
make lint          # ruff static checks
make test          # full suite, 100% coverage required
make build         # wheel + sdist → dist/

Rebuild the Packt examples

make examples

Requires examples/packt-style.docx (real Packt template). Produces:

File	Description
examples/packt-style.styles.json	extracted style identity
examples/packt-style.bundle/	full extraction bundle
examples/packt-style-example.docx	compact style surface test
examples/packt-book-chapter.docx	long-form chapter proof
examples/01-transformer.docx	math-heavy transformer chapter
examples/packt-style-author-guide.docx	author tutorial

---

Documentation

Guide	Audience
Quick Start	Just getting started
CLI Reference	Every command and flag
Style Guide	How to annotate Markdown with styles
CI/CD Integration	Automated pipelines
Packt Author Guide	Publisher content workflows
Architecture	Design decisions and internals
Release Process	How to cut a release
edgemint Claude Skill	AI agent integration (general)
edgemint-packt Claude Skill	AI agent integration (Packt)

---

Contributing

See CONTRIBUTING.md. The short version:

make bootstrap && make test   # must pass at 100% coverage

All PRs must pass lint + full test suite. See docs/release-process.md for the release checklist.

---

License

Apache 2.0 © Raphaël Mansuy