https://github.com/raphaelmansuy/edgemint
Extract DOCX template styles into JSON. Regenerate pixel-perfect branded documents from Markdown. CLI + AI agent ready.
https://github.com/raphaelmansuy/edgemint
ai-agent claude cli document-generation docx markdown pandoc publishing python word
Last synced: 2 months ago
JSON representation
Extract DOCX template styles into JSON. Regenerate pixel-perfect branded documents from Markdown. CLI + AI agent ready.
- Host: GitHub
- URL: https://github.com/raphaelmansuy/edgemint
- Owner: raphaelmansuy
- License: other
- Created: 2026-04-12T08:30:24.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-04-12T10:20:07.000Z (2 months ago)
- Last Synced: 2026-04-12T10:24:13.256Z (2 months ago)
- Topics: ai-agent, claude, cli, document-generation, docx, markdown, pandoc, publishing, python, word
- Language: Python
- Homepage: https://pypi.org/project/edgemint/
- Size: 10.1 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# edgemint
> **Extract the visual identity from any Word template. Regenerate pixel-perfect branded documents from Markdown. Every time. In seconds.**
[](https://pypi.org/project/edgemint/)
[](https://pypi.org/project/edgemint/)
[](https://github.com/raphaelmansuy/edgemint/actions/workflows/ci.yml)
[](LICENSE)
[](https://ghcr.io/raphaelmansuy/edgemint)
---
## 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
```bash
# 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
```bash
# 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
```bash
# 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:
```yaml
# .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/`](.claude/skills/):
| Skill | Purpose |
|-------|--------|
| [edgemint](.claude/skills/edgemint/SKILL.md) | General DOCX generation for any template |
| [edgemint-packt](.claude/skills/edgemint-packt/SKILL.md) | Packt publisher house-style specialisation |
Install the general skill globally:
```bash
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):
```bash
# 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
```bash
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 
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
```bash
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
```bash
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](docs/quick-start.md) | Just getting started |
| [CLI Reference](docs/cli-reference.md) | Every command and flag |
| [Style Guide](docs/style-guide.md) | How to annotate Markdown with styles |
| [CI/CD Integration](docs/cicd-integration.md) | Automated pipelines |
| [Packt Author Guide](docs/packt-author-guide.md) | Publisher content workflows |
| [Architecture](docs/architecture.md) | Design decisions and internals |
| [Release Process](docs/release-process.md) | How to cut a release |
| [edgemint Claude Skill](.claude/skills/edgemint/SKILL.md) | AI agent integration (general) |
| [edgemint-packt Claude Skill](.claude/skills/edgemint-packt/SKILL.md) | AI agent integration (Packt) |
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:
```bash
make bootstrap && make test # must pass at 100% coverage
```
All PRs must pass lint + full test suite. See [docs/release-process.md](docs/release-process.md)
for the release checklist.
---
## License
[Apache 2.0](LICENSE) © Raphaël Mansuy