{"id":48746612,"url":"https://github.com/raphaelmansuy/edgemint","last_synced_at":"2026-04-12T12:01:37.331Z","repository":{"id":350826798,"uuid":"1208407616","full_name":"raphaelmansuy/edgemint","owner":"raphaelmansuy","description":"Extract DOCX template styles into JSON. Regenerate pixel-perfect branded documents from Markdown. CLI + AI agent ready.","archived":false,"fork":false,"pushed_at":"2026-04-12T10:20:07.000Z","size":10582,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-12T10:24:13.256Z","etag":null,"topics":["ai-agent","claude","cli","document-generation","docx","markdown","pandoc","publishing","python","word"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/edgemint/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphaelmansuy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T08:30:24.000Z","updated_at":"2026-04-12T10:20:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raphaelmansuy/edgemint","commit_stats":null,"previous_names":["raphaelmansuy/edgemint"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/raphaelmansuy/edgemint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fedgemint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fedgemint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fedgemint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fedgemint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphaelmansuy","download_url":"https://codeload.github.com/raphaelmansuy/edgemint/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fedgemint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31713876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-12T06:22:27.080Z","status":"ssl_error","status_checked_at":"2026-04-12T06:21:52.710Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","cli","document-generation","docx","markdown","pandoc","publishing","python","word"],"created_at":"2026-04-12T12:01:35.705Z","updated_at":"2026-04-12T12:01:37.325Z","avatar_url":"https://github.com/raphaelmansuy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# edgemint\n\n![edgemint hero](./assets/01-hero.jpg)\n\n\u003e **Extract the visual identity from any Word template. Regenerate pixel-perfect branded documents from Markdown. Every time. In seconds.**\n\n[![PyPI](https://img.shields.io/pypi/v/edgemint)](https://pypi.org/project/edgemint/)\n[![Python](https://img.shields.io/pypi/pyversions/edgemint)](https://pypi.org/project/edgemint/)\n[![CI](https://github.com/raphaelmansuy/edgemint/actions/workflows/ci.yml/badge.svg)](https://github.com/raphaelmansuy/edgemint/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/raphaelmansuy/edgemint)\n\n---\n\n## Why does this exist?\n\nYou have a beautiful `.docx` template. Corporate fonts, precise spacing, branded headings. Your designer spent weeks on it.\n\nNow you need to produce 50 reports with that exact look — from Markdown your team writes in Git repos, wikis, and notebooks.\n\n**What happens today:**\n\n```\n  THE PAINFUL WAY\n  ───────────────────────────────────────────────────────────────\n  1. Open Word\n  2. Copy-paste your Markdown content\n  3. Manually apply Heading 1... Heading 2... Body Text...\n  4. Fix the spacing. Again.\n  5. Fix the fonts. Again.\n  6. Realize the numbered list is wrong. Fix it. Again.\n  7. Repeat for the next 49 documents.\n\n  Total time: hours    Errors: guaranteed    Will to live: declining\n```\n\n**What should happen:**\n\n```\n  THE edgemint WAY\n  ───────────────────────────────────────────────────────────────\n  1. Extract styles from your template     (once,  ~1 second)\n  2. Write content in Markdown             (the fun part)\n  3. Run one command                       (\u003c 5 seconds)\n  4. Get a perfectly styled .docx          (every time)\n\n  Total time: seconds    Errors: zero    Will to live: restored\n```\n\n`edgemint` is a CLI that extracts the complete visual identity from any `.docx`\ntemplate into a portable JSON file, then regenerates new documents from Markdown\nor AsciiDoc while preserving every font, color, spacing, and border — losslessly.\n\n---\n\n## How it works\n\n```\n  YOUR TEMPLATE          YOUR CONTENT           YOUR OUTPUT\n  ─────────────          ────────────           ───────────\n\n  ┌────────────┐          ┌────────────┐         ┌────────────┐\n  │ branded    │          │ content.md │         │ branded    │\n  │ .docx      │          │ (Markdown) │         │ .docx      │\n  └─────┬──────┘          └─────┬──────┘         └────────────┘\n        │                       │                      ▲\n        │ extract-styles        │                      │\n        ▼                       │    apply-styles      │\n  ┌────────────┐                └─────────────────────►┘\n  │ styles.json│\n  │ (identity) │\n  └────────────┘\n\n  \"what it looks like\"   \"what it says\"     \"both, together\"\n```\n\nTwo commands. Any template. Any content. Every time.\n\n---\n\n## Install\n\n```bash\n# Recommended: install as a CLI tool (works on macOS, Linux, Windows)\npipx install 'edgemint[pandoc]'\n\n# Lightweight (style extraction + diff only, no Pandoc)\npipx install edgemint\n\n# Inside a virtual environment or CI\npip install 'edgemint[pandoc]'\n\n# Docker (zero local dependencies)\ndocker pull ghcr.io/raphaelmansuy/edgemint:latest\n```\n\n\u003e **macOS note**: `pip install` is blocked by Homebrew's Python. Use `pipx install` or activate a virtual environment first.\n\n---\n\n## 60-second demo\n\n```bash\n# 1. See what styles are in your template\nedgemint info brand.docx\n\n# 2. Extract the visual identity\nedgemint extract-styles brand.docx -o styles.json\n\n# 3. Write your content in Markdown, then generate\nedgemint apply-styles report.md styles.json -o report.docx\n```\n\nOpen `report.docx`. Every font, color, and spacing is **identical** to your template.\n\n---\n\n## Full round-trip with images\n\n```bash\n# Extract everything: content + styles + media\nedgemint extract source.docx -o project/\n# → project/content.md   (Pandoc Extended Markdown)\n# → project/styles.json  (complete visual identity)\n# → project/media/       (all embedded images)\n\n# Edit project/content.md, then regenerate\nedgemint apply-styles project/content.md project/styles.json \\\n  -o rebuilt.docx --media project/media\n```\n\n---\n\n## Commands\n\n```\nedgemint extract-styles   template.docx  -o styles.json\nedgemint extract          document.docx  -o project/\nedgemint apply-styles     content.md styles.json  -o output.docx\nedgemint apply-styles     content.adoc styles.json  -o output.docx --input-format asciidoc\nedgemint diff             old.json new.json\nedgemint validate         styles.json\nedgemint info             template.docx\nedgemint schema\n```\n\n| Command | Needs Pandoc? | What it does |\n|---------|:---:|---|\n| `extract-styles` | No | `.docx` → `styles.json` |\n| `extract` | Yes | `.docx` → `content.md` + `styles.json` + `media/` |\n| `apply-styles` | Yes | `content.md` + `styles.json` → `.docx` |\n| `diff` | No | compare two `styles.json` files |\n| `validate` | No | check `styles.json` schema |\n| `info` | No | quick `.docx` style summary |\n| `schema` | No | print the JSON Schema |\n\n---\n\n## Use in CI/CD\n\nGenerate styled documents on every push — no Word needed:\n\n```yaml\n# .github/workflows/generate-docs.yml\njobs:\n  generate:\n    runs-on: ubuntu-latest\n    container: ghcr.io/raphaelmansuy/edgemint:latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: |\n          for md in reports/*.md; do\n            edgemint apply-styles \"$md\" brand/styles.json \\\n              -o \"output/$(basename $md .md).docx\"\n          done\n      - uses: actions/upload-artifact@v4\n        with:\n          name: reports\n          path: output/*.docx\n```\n\nPush Markdown → get styled `.docx` artifacts. Every commit. Automatically.\n\n---\n\n## AI Agent Integration\n\nedgemint is designed to be a **first-class tool for AI coding agents**. When an\nagent (Claude, GPT-4o, Gemini, Cursor, etc.) needs to produce a formatted Word\ndocument, the workflow is:\n\n```\n  AGENT WORKFLOW\n  ──────────────────────────────────────────────────────────────────\n  User: \"Write a Q3 report using our brand template.\"\n\n  1. Agent reads styles.json  (knows every branded paragraph/char style)\n  2. Agent writes content.md  (Markdown + custom-style annotations)\n  3. Agent calls edgemint      edgemint apply-styles content.md styles.json -o report.docx\n  4. Agent returns report.docx (pixel-perfect branded output)\n\n  No Word. No manual styling. No human in the loop.\n```\n\nThis pattern works for:\n- **Report generation** — audit reports, weekly updates, release notes\n- **Book authoring** — Packt, O'Reilly, or any publisher template\n- **Legal documents** — contract templates, NDAs, briefs\n- **Engineering docs** — RFCs, architecture proposals, ADRs\n- **Batch pipelines** — generate 100 branded PDFs from one template in CI\n\n### Install the Claude Code Skill\n\nThe repo ships two ready-to-use Claude Code skills in [`.claude/skills/`](.claude/skills/):\n\n| Skill | Purpose |\n|-------|--------|\n| [edgemint](.claude/skills/edgemint/SKILL.md) | General DOCX generation for any template |\n| [edgemint-packt](.claude/skills/edgemint-packt/SKILL.md) | Packt publisher house-style specialisation |\n\nInstall the general skill globally:\n\n```bash\nmkdir -p ~/.claude/skills/edgemint\ncp .claude/skills/edgemint/SKILL.md ~/.claude/skills/edgemint/SKILL.md\n```\n\nOr use it project-locally (Claude Code picks it up automatically):\n\n```bash\n# already there — just open Claude Code in this repo\nls .claude/skills/\n```\n\n### Conversational example\n\nOnce the skill is installed, an agent session looks like this:\n\n```\nUser:  Extract styles from our brand.docx, then write a two-page\n       executive summary about Q3 sales using the template.\n\nClaude: I'll extract the styles first, then write the content.\n\n  $ edgemint extract-styles brand.docx -o styles.json\n  ✓ 47 styles extracted\n\n  [writes content.md with correct custom-style annotations]\n\n  $ edgemint apply-styles content.md styles.json -o executive-summary.docx\n  ✓ executive-summary.docx (42 KB)\n\n  Done — executive-summary.docx is ready to submit.\n```\n\n---\n\n## Audit style changes between template versions\n\n```bash\nedgemint diff brand-v1.json brand-v2.json\n\nCHANGED  Heading1\n  font.size_pt: 16.0 → 18.0\n  font.color: #2F5496 → #1A3C6E\nADDED    Subtitle\nREMOVED  BodyTextIndent\n```\n\nVersion-control your `styles.json` and review brand changes in PRs.\n\n---\n\n## What is preserved\n\n```\n  Paragraph styles    LOSSLESS   custom-style fenced divs\n  Character styles    LOSSLESS   custom-style bracketed spans\n  Bold / italic       LOSSLESS   standard Markdown syntax\n  Footnotes           LOSSLESS   [^id] syntax\n  Images              LOSSLESS   ![alt](media/x.png)\n  Tables              LOSSLESS   pipe / grid tables\n  Math (LaTeX)        LOSSLESS   $...$ and $$...$$\n  Theme / colors      LOSSLESS   styles.json sidecar\n  Headers / footers   LOSSLESS   styles.json sidecar\n  ──────────────────────────────────────────────────────\n  Track changes       LOST       accepted only\n  Comments            LOST       no Markdown equivalent\n  VBA / Macros        LOST       stripped (security)\n```\n\nNo surprises. No silent degradation. Losses are always logged as warnings.\n\n---\n\n## Development workflow\n\n```bash\ngit clone https://github.com/raphaelmansuy/edgemint\ncd edgemint\nmake bootstrap     # create .venv, install all deps\nmake doctor        # verify toolchain\nmake fmt           # auto-format\nmake lint          # ruff static checks\nmake test          # full suite, 100% coverage required\nmake build         # wheel + sdist → dist/\n```\n\n### Rebuild the Packt examples\n\n```bash\nmake examples\n```\n\nRequires `examples/packt-style.docx` (real Packt template). Produces:\n\n| File | Description |\n|------|-------------|\n| `examples/packt-style.styles.json` | extracted style identity |\n| `examples/packt-style.bundle/` | full extraction bundle |\n| `examples/packt-style-example.docx` | compact style surface test |\n| `examples/packt-book-chapter.docx` | long-form chapter proof |\n| `examples/01-transformer.docx` | math-heavy transformer chapter |\n| `examples/packt-style-author-guide.docx` | author tutorial |\n\n---\n\n## Documentation\n\n| Guide | Audience |\n|-------|---------|\n| [Quick Start](docs/quick-start.md) | Just getting started |\n| [CLI Reference](docs/cli-reference.md) | Every command and flag |\n| [Style Guide](docs/style-guide.md) | How to annotate Markdown with styles |\n| [CI/CD Integration](docs/cicd-integration.md) | Automated pipelines |\n| [Packt Author Guide](docs/packt-author-guide.md) | Publisher content workflows |\n| [Architecture](docs/architecture.md) | Design decisions and internals |\n| [Release Process](docs/release-process.md) | How to cut a release |\n| [edgemint Claude Skill](.claude/skills/edgemint/SKILL.md) | AI agent integration (general) |\n| [edgemint-packt Claude Skill](.claude/skills/edgemint-packt/SKILL.md) | AI agent integration (Packt) |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The short version:\n\n```bash\nmake bootstrap \u0026\u0026 make test   # must pass at 100% coverage\n```\n\nAll PRs must pass lint + full test suite. See [docs/release-process.md](docs/release-process.md)\nfor the release checklist.\n\n---\n\n## License\n\n[Apache 2.0](LICENSE) © Raphaël Mansuy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fedgemint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphaelmansuy%2Fedgemint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fedgemint/lists"}