# 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+.

```bash
pip install markidocx
```

For development:

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

Optional diagram renderer extras:

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

---

## Quick Start

### 1. Create a manifest

```yaml
# 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

```bash
markidocx build project.yaml
```

### 3. Import an edited DOCX

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

### 4. Check for drift

```bash
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

```bash
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.

```bash
markidocx mcp
```

---

## Development

```bash
# 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](LICENSE).