marki-docx/README.md

markidocx

Markdown ↔ DOCX round-trip editing system.

Markdown is the canonical structured source. Word documents are editorial projections — generated for review, edited by collaborators, then imported back with changes redistributed to the original Markdown files.

---

Overview

markidocx solves a common authoring problem: you want to write and version-control content in Markdown, but collaborators review and edit in Word. Rather than treating the DOCX as the source of truth, markidocx keeps Markdown authoritative and makes the round-trip deterministic and inspectable.

manifest + Markdown sources
    ↓  resolve project (FR-100)
    ↓  compose + export → DOCX (FR-200)
     [Word editorial review]
    ↓  import DOCX → Markdown (FR-300)
    ↓  redistribute to source files (FR-400)
    ↓  validate + drift report (FR-700)
evidence artefacts

---

Features

• Build — compose multi-file Markdown projects into a styled DOCX
• Import — parse an edited DOCX back to Markdown, redistributing changes to source files
• Validate — structural drift detection between original and re-imported content
• LEVEL1 — headings, lists, tables, footnotes, images, links
• LEVEL3 — cross-references, numbered figures, auto-diagrams (Mermaid / Graphviz / PlantUML), bibliography
• Document families — article, book, website; extensible via template registration
• Three interfaces — CLI, REST service, MCP tools over a shared functional core

---

Installation

Requires Python 3.11+.

pip install markidocx

For development:

git clone https://github.com/tegwick/marki-docx
cd marki-docx
pip install -e ".[dev]"

Optional diagram renderer extras:

pip install "markidocx[diagram-mermaid]"
pip install "markidocx[diagram-graphviz]"

---

Quick Start

1. Create a manifest

# project.yaml
project:
  name: My Document
  feature_level: LEVEL1
  family: article

sources:
  - intro.md
  - body.md
  - conclusion.md

output:
  docx: dist/my-document.docx

2. Build a DOCX

markidocx build project.yaml

3. Import an edited DOCX

markidocx import project.yaml dist/my-document-reviewed.docx

4. Check for drift

markidocx compare project.yaml dist/my-document-reviewed.docx

---

CLI Reference

markidocx build <manifest>       Build DOCX from Markdown sources
markidocx import <manifest> <docx>  Import edited DOCX → Markdown
markidocx compare <manifest> <docx> Drift analysis (baseline vs re-import)
markidocx validate <manifest>    Validate manifest file
markidocx workflow <name>        Run a named end-to-end workflow
markidocx serve                  Start REST service
markidocx mcp                    Start MCP server
markidocx template list          List available template families

All commands accept --json for machine-readable output.

---

REST Service

markidocx serve --dev

API is available at http://localhost:8000. Interactive docs at /docs.

---

MCP Tools

markidocx exposes its full functional surface as MCP tools, making it accessible to AI agents and automation pipelines.

markidocx mcp

---

Development

# Run tests
pytest

# Lint
ruff check .

# Type-check
mypy src/

---

Architecture

All three interfaces (CLI, REST, MCP) are thin adapters over a shared functional core. No interface-specific logic lives outside its adapter layer.

Module	Responsibility
manifest.py	Project manifest loading and validation
builder.py	Markdown → DOCX composition
importer.py	DOCX → Markdown round-trip
differ.py	Structural drift detection
templates.py	Template and style family management
workflows.py	Composite end-to-end workflows
evidence.py	Evidence and report assembly
errors.py	Structured warning and failure records
level3.py	LEVEL3 feature detection and disclosure
xref.py	Cross-reference helpers
figures.py	Numbered figure helpers
diagrams.py	Auto-diagram rendering
bibliography.py	Citation and references section
rest.py	FastAPI REST interface
mcp_server.py	FastMCP tool interface
cli.py	Typer CLI interface

---

License

See LICENSE.