Enterprise‑grade document automation toolkit for deterministic DOCX and Markdown workflows.
docutil is a lightweight, CLI‑first Python utility built for engineers, analysts, and automation teams who need repeatable, scriptable, CI‑safe document processing.
It provides reliable conversions and batch processing between:
• DOCX ↔ Markdown (GitHub Flavored Markdown)
• Folder‑wide batch conversions
• Project scaffolding
• Metadata inspection
• Environment diagnostics
Designed specifically for automation, consulting, and enterprise environments where reproducibility and reliability matter more than GUIs.
- Overview
- Design Philosophy
- Features
- Architecture
- Installation
- Quick Start
- Command Reference
- Batch Workflows
- CI/CD Usage
- Testing
- Development
- Troubleshooting
- Roadmap
docutil replaces manual document conversion tasks with deterministic, scriptable commands.
Typical use cases:
• Convert Word deliverables into Markdown for GitHub
• Convert Markdown documentation back to DOCX for clients
• Batch migrate entire repositories
• Run document transformations inside CI pipelines
• Standardize documentation workflows across teams
docutil intentionally avoids:
❌ GUIs
❌ heavy runtime dependencies
❌ OS‑specific installers
❌ hidden side effects
❌ non‑deterministic output
Instead it prioritizes:
✅ CLI‑first
✅ deterministic output
✅ automation friendly
✅ testability
✅ CI safety
✅ minimal dependencies
If it can’t run in a headless CI environment, it doesn’t belong here.
• DOCX → Markdown (GFM)
• Markdown → DOCX
• Stable output formatting
• No automatic line wrapping
• ATX headings (# style)
• recursive scanning
• dry‑run preview
• progress bars (TTY aware)
• parallel workers
• safe overwrite control
• out‑folder support
• CI friendly logging
• project scaffolding
• metadata inspection
• environment diagnostics (doctor)
• structured logging
• pytest test suite
• type checking (mypy)
• linting (ruff)
docutil/
│
├── cli.py # Typer CLI interface
├── conversions/ # Conversion engines
├── inspect/ # Metadata utilities
├── templates/ # Project scaffolding
├── doctor.py # Environment diagnostics
├── logging_utils.py # Centralized logging
└── tests/ # Fast unit tests
• CLI is thin
• business logic lives in modules
• deterministic I/O
• side effects explicit
• easy to test
Recommended:
conda install -c conda-forge pandoc
pip install -e .
pip install -e .[dev]
Includes:
• pytest
• ruff
• mypy
DOCX → Markdown
docutil docx2md report.docx
Markdown → DOCX
docutil md2docx notes.md
docutil batch docx2md ./docs --recursive
docutil batch docx2md ./docs --dry-run
docutil batch md2docx ./docs --out-folder ./out
docutil batch docx2md ./docs --workers 4
docutil scaffold project MyProject .
docutil doctor
docutil version
docutil doctor
docutil docx2md <file>
docutil md2docx <file>
docutil batch <mode> <folder>
docutil scaffold project <name> <dir>
docutil inspect docx <file>
docutil batch docx2md docs --recursive --dry-run
docutil batch docx2md docs --recursive --workers 4
docutil batch md2docx docs --out-folder out
docutil batch docx2md docs --recursive --no-progress
Example GitHub Actions step:
docutil batch docx2md docs --recursive --no-progress
No progress bars = clean logs.
Run locally:
pytest -q
Tests are:
• fast (<1s)
• Pandoc mocked
• deterministic
Lint:
ruff check .
Type check:
mypy src
conda install -c conda-forge pandoc
docutil doctor
Increase workers:
--workers 4
Planned:
• richer batch summaries
• optional integration tests
• packaging for PyPI
• additional inspection tools
Internal / Enterprise use