Metadata-Version: 2.4
Name: mddocx-native
Version: 1.2.1
Summary: Deterministic Markdown to native, editable Microsoft Word DOCX compiler
Author: Tasin Ahmed
License-Expression: MIT
Project-URL: Homepage, https://github.com/TasinAhmed2508/mddocx
Project-URL: Repository, https://github.com/TasinAhmed2508/mddocx
Project-URL: Issues, https://github.com/TasinAhmed2508/mddocx/issues
Project-URL: Changelog, https://github.com/TasinAhmed2508/mddocx/blob/main/CHANGELOG.md
Keywords: markdown,docx,microsoft-word,document-conversion,ooxml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: python-docx>=1.1
Requires-Dist: lxml>=5.0
Requires-Dist: Pillow>=10.0
Requires-Dist: Pygments>=2.17
Requires-Dist: PyYAML>=6.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: prompt-toolkit>=3.0
Provides-Extra: math
Requires-Dist: latex2mathml>=3.81.0; extra == "math"
Provides-Extra: frontmatter
Requires-Dist: PyYAML>=6.0; extra == "frontmatter"
Provides-Extra: images
Requires-Dist: Pillow>=10.0; extra == "images"
Requires-Dist: CairoSVG>=2.7; extra == "images"
Requires-Dist: defusedxml>=0.7; extra == "images"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# mddocx

[![PyPI](https://img.shields.io/pypi/v/mddocx-native)](https://pypi.org/project/mddocx-native/)
[![Python](https://img.shields.io/pypi/pyversions/mddocx-native)](https://pypi.org/project/mddocx-native/)
[![CI](https://github.com/TasinAhmed2508/mddocx/actions/workflows/ci.yml/badge.svg)](https://github.com/TasinAhmed2508/mddocx/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/TasinAhmed2508/mddocx)](https://github.com/TasinAhmed2508/mddocx/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Deterministic Markdown-to-DOCX compilation for professional, editable Microsoft Word documents.

mddocx converts Markdown into native Word structures instead of screenshots or flattened pages. Headings, lists, tables, equations, charts, links, references, footnotes, headers, footers, and other document elements remain editable in Microsoft Word.

## What it does

- Converts Markdown files or strings into native DOCX documents.
- Preserves editable Word headings, paragraphs, lists, tables, hyperlinks, and code blocks.
- Supports nested lists, task lists, blockquotes, callouts, page breaks, and section breaks.
- Produces editable Word equations using OMML rather than images.
- Creates editable Office charts backed by embedded Excel workbooks.
- Supports CSV and JSON data for charts and native Word tables.
- Handles images, captions, bookmarks, cross-references, footnotes, endnotes, and citations.
- Supports themes, fonts, templates, right-to-left text, headers, footers, tables of contents, and page fields.
- Provides project mode for compiling multiple Markdown chapters into one document.
- Includes diagnostics, document inspection, accessibility checks, and profiling utilities.
- Provides privacy-aware metadata handling for exported AI/chat conversations.

## Installation

mddocx requires Python 3.11 or newer.

### Install from PyPI

The distribution is published as `mddocx-native`; the Python import and command remain `mddocx`:

```bash
python -m pip install --upgrade mddocx-native
```

Verify the installation:

```bash
mddocx --version
mddocx doctor
```

### Install a downloaded wheel

Download the `.whl` file from the [latest GitHub Release](https://github.com/TasinAhmed2508/mddocx/releases/latest), open a terminal in the download directory, and run:

```bash
python -m pip install ./mddocx_native-1.2.1-py3-none-any.whl
```

On Windows PowerShell, the equivalent command is:

```powershell
python -m pip install .\mddocx_native-1.2.1-py3-none-any.whl
```

You can also install the wheel directly from the v1.2.1 GitHub Release:

```bash
python -m pip install "https://github.com/TasinAhmed2508/mddocx/releases/download/v1.2.1/mddocx_native-1.2.1-py3-none-any.whl"
```

### Install from GitHub

```bash
python -m pip install "git+https://github.com/TasinAhmed2508/mddocx.git@v1.2.1"
```

### Install for local development

```bash
git clone https://github.com/TasinAhmed2508/mddocx.git
cd mddocx
python -m pip install -e ".[dev]"
```

Optional features:

```bash
python -m pip install "mddocx-native[math]"
python -m pip install "mddocx-native[images]"
python -m pip install "mddocx-native[math,images]"
```

## Quick start

Create a file named report.md:

    # Quarterly Report

    ## Summary

    This report is generated from Markdown and remains fully editable in Word.

    | Metric | Value |
    | --- | ---: |
    | Revenue | 125,000 |
    | Growth | 18% |

Convert it to Word:

    mddocx report.md -o report.docx

## Command-line interface

    mddocx document.md -o document.docx
    mddocx document.md --theme academic
    mddocx document.md --template company.docx
    mddocx document.md --toc --page-numbers
    mddocx document.md --header "Project Report" --footer "Confidential"
    mddocx document.md --diagnostics-json diagnostics.json
    mddocx inspect document.docx --strict
    mddocx accessibility document.docx --strict
    mddocx doctor
    mddocx api --json

For multi-file document projects:

    mddocx project init report
    mddocx build report
    mddocx project info report
    mddocx watch report

For interactive use:

    mddocx shell

Run mddocx --help for the complete command reference.

## Python API

    from mddocx import RenderConfig, render, render_string

    render("report.md", "report.docx")

    config = RenderConfig(theme="modern")
    document = render_string("# Generated report\n\nEditable Word content.", config=config)

    with open("generated.docx", "wb") as file:
        file.write(document)

The public API is documented in docs/API_STABILITY.md and can also be inspected with mddocx api --json.

## YAML front matter

Document settings can be defined at the top of a Markdown file:

    ---
    title: Research Report
    author: Example Author
    theme: academic
    toc: true
    page_numbers: true
    auto_landscape_tables: true
    header: Research Group
    footer: Confidential
    ---

## Privacy and security defaults

- Remote resources are disabled by default.
- HTTPS image downloads can be explicitly enabled and restricted by domain.
- Local resource paths cannot escape the document or project directory.
- Download size, MIME type, redirects, and network destinations are constrained.
- SVG parsing rejects external references and uses hardened XML handling.
- Code blocks and TeX are never executed.
- AI/chat export metadata is removed conservatively before Markdown parsing when enabled.

## Project layout

    mddocx/
    ├── src/mddocx/        # Package source code
    ├── docs/              # User and technical documentation
    ├── dist/              # Local build output, when generated
    ├── .github/workflows/ # CI and release automation
    ├── pyproject.toml     # Package metadata and build configuration
    └── README.md          # Project overview and usage guide

## Documentation

Detailed documentation is available in the docs directory, including compatibility, API stability, interactive CLI, charts and data, AI export metadata, accessibility, and extensions.

## Releases

Release builds are generated by GitHub Actions. Each versioned release publishes the wheel and source archive as downloadable GitHub Release assets.

- [Latest release](https://github.com/TasinAhmed2508/mddocx/releases/latest)
- [All releases](https://github.com/TasinAhmed2508/mddocx/releases)
- [All version tags](https://github.com/TasinAhmed2508/mddocx/tags)
- [PyPI package](https://pypi.org/project/mddocx-native/)

## License

Released under the [MIT License](LICENSE).
