generated from coulomb/repo-seed
183 lines
4.3 KiB
Markdown
183 lines
4.3 KiB
Markdown
# 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).
|