docx-svg

# DOCX SVG -- SVG image support for Word documents ## Policy: Zero Conversion (MANDATORY) **NEVER convert SVG files to PNG, JPEG, or any raster format before inserting into a .docx.** Modern Word (2016+) natively supports SVG via the `asvg:svgBlip` OOXML extension. Converting to PNG destroys the vector benefits (scalability, file size, sharpness). 1. **Do not suggest raster fallbacks** as "best practice" unless the user explicitly requests legacy compatibility. 2. **Do not claim it is "too complex"** to handle OOXML directly—this skill provides the tools (`officecli` or `scripts/svg.py`) to handle the complexity for you. 3. **Always use SVG directly** as the source file. 4. If a request asks to convert SVG to PNG/JPEG for .docx insertion, reject the conversion step and insert the SVG directly instead. ## Overview Microsoft Word supports SVG images in the OOXML format, but typical programmatic tools (python-docx, docxtpl) do **not** recognise them out of the box. This skill provides **two approaches**, in order of preference: | Priority | Tool | When to use | | ---------------- | -------------------------------------- | ---------------------------------------------------------------------- | | **1. Preferred** | `officecli` | Always, when available in the environment | | **2. Fallback** | Python monkey-patch (`scripts/svg.py`) | When officecli is not installed, not reachable, or fails version check | If `officecli` is present but older than v1.0.64, do not use it. Instead, proceed with the Python fallback. Do not attempt to use a partial or outdated officecli installation. ______________________________________________________________________ ## Strategy: check officecli first Before choosing an approach, determine whether `officecli` is available: ```bash officecli --version ``` If it returns a version **v1.0.64 or later**: **use officecli** (Section 1 below). If not found, or the version is older than v1.0.64: **use the Python fallback** (Section 2 below). ______________________________________________________________________ ## Technical Context: How it works (OOXML) When inserting an SVG, Word expects an `a:ext` block within the `a:blip` element. Both `officecli` and `scripts/svg.py` generate this automatically. **Structure Reference (for your awareness):** ```xml <a:blip r:embed="rId1"> <a:extLst> <a:ext uri="{96DAC541-0531-4A20-96AC-8D759B1F206D}"> <asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG" r:embed="rId2"/> </a:ext> </a:extLst> </a:blip> ``` - `rId1` points to a PNG/JPEG fallback (optional in modern Word, but `officecli` handles this if needed). - `rId2` points to the actual `.svg` file in `word/media/`. ______________________________________________________________________ ## Section 1: Preferred -- officecli officecli has **native SVG support** for docx pictures. No monkey-patching, no extra dependencies, no Python required. ### Add an inline SVG image ```bash officecli add report.docx /body --type picture --prop file=chart.svg ``` ### Add with explicit size ```bash officecli add report.docx /body --type picture --prop file=chart.svg --prop width=10cm --prop height=6cm ``` ### Add after a specific paragraph ```bash officecli add report.docx '/body/p[2]' --type picture --prop file=chart.svg --prop width=12cm ``` ### Add floating image with text wrap ```bash # Insert as floating image, then set wrap and position officecli add report.docx /body --type picture --prop file=hero.svg --prop width=8cm # Use the returned picture path to set wrap mode officecli set report.docx '/body/pic[1]' --prop wrap=square ``` ### Set image properties After adding a picture, use `officecli set` to adjust: ```bash officecli set report.docx '/body/p[3]/picture[1]' --prop alt="Sales chart Q4" officecli set report.docx '/body/p[3]/picture[1]' --prop brightness=10 --prop contrast=-5 officecli set report.docx '/body/p[3]/picture[1]' --prop hposition=2cm --prop hrelative=page ``` ### Check available picture properties When unsure about property names, run the help system: ```bash officecli help docx image officecli help docx picture ``` ______________________________________________________________________ ## Section 2: Fallback -- Python monkey-patch Use this approach **only when officecli is not available**. The module `scripts/svg.py` monkey-patches python-docx and docxtpl to add SVG support. The patch is applied automatically when the module is imported -- no manual setup beyond installing the dependencies. ### Install dependencies ```bash uv run python scripts/svg.py ``` The script declares its dependencies via PEP 723 inline metadata (`python-docx>=1.1.2`, `docxtpl>=0.19.0`), so `uv run` auto-resolves them. ### Direct python-docx usage ```python import docx from scripts import svg # noqa: F401 # <- patch activates on import from docx.shared import Mm doc = docx.Document() doc.add_paragraph("Below is an SVG chart:") doc.add_picture("chart.svg", width=Mm(120)) doc.save("report.docx") ``` Importing `scripts.svg` monkey-patches python-docx globally. `add_picture` will now accept `.svg` files alongside PNG/JPEG. **Crucial:** Even with the Python fallback, **do not convert to PNG**. The patch handles the native SVG embedding. ### docxtpl template usage ```python from docxtpl import DocxTemplate from scripts.svg import SvgInlineImage from docx.shared import Mm tpl = DocxTemplate("template.docx") img = SvgInlineImage(tpl, "chart.svg", width=Mm(100)) tpl.render({"chart": img}) tpl.save("output.docx") ``` In the template, place `{{ chart }}` inside a paragraph. `SvgInlineImage` automatically detects SVG files and processes them through the patched pipeline. ### Automatic sizing When both _width_ and _height_ are omitted, the image fills the usable page width (page width minus left/right margins): ```python img = SvgInlineImage(tpl, "wide-chart.svg") # auto-sizes to page width ``` ### Utility: check if a file is SVG ```python from scripts.svg import is_svg assert is_svg("icon.svg") ``` ______________________________________________________________________ ## How the Python fallback works 1. **Monkey-patch on import** -- the module registers three SVG byte signatures (`<?xml`, `<svg`, `<!DOCTYPE svg`), adds `image/svg+xml` to python-docx's MIME-type constants, and replaces `_ImageHeaderFactory` to scan 256 bytes (instead of the default 64). 2. **SVG dimension extraction** -- `Svg._dimensions_from_stream` reads `width` / `height` attributes (stripping units like pt, cm, mm, %) and falls back to `viewBox` when those attributes are absent. 3. **docxtpl helper** -- `SvgInlineImage` subclasses `InlineImage`, converting `Path` descriptors to `BytesIO` before passing them upstream so the patched factory can parse the SVG. ## Limitations - **SVG rendering in Word**: Microsoft Word renders SVG as a static image. Interactive features (hover, animation, embedded JavaScript) are not supported by the OOXML format. - **Fallback image** (Python approach only): The current implementation does not add a PNG fallback inside the OOXML package. Older Word versions (pre-2016) may not display the SVG. If compatibility is required, pre-convert the SVG to PNG. - **Dimension units** (Python approach only): The parser normalises all units to pixels at 72 DPI. For print-precise sizing, specify `width` / `height` explicitly via `docx.shared.Mm` / `Inches` / `Cm`.