Metadata-Version: 2.4
Name: mddocx-native
Version: 1.4.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: bijoy2unicode==0.1.1
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: latex2mathml>=3.81.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: academic
Requires-Dist: citeproc-py<0.11,>=0.10.3; extra == "academic"
Provides-Extra: mathjax
Requires-Dist: nodejs-wheel>=24.19.0; extra == "mathjax"
Provides-Extra: all
Requires-Dist: latex2mathml>=3.81.0; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: CairoSVG>=2.7; extra == "all"
Requires-Dist: defusedxml>=0.7; extra == "all"
Requires-Dist: citeproc-py<0.11,>=0.10.3; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff==0.15.10; 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 local, HTTPS, and Base64 `data:image/...;base64,...` images, plus 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.
- Accepts common equation syntax copied from ChatGPT, Claude, Gemini, and other MathJax/LaTeX-producing assistants.
- Keeps multilingual documents correct with per-script font slots, right-to-left direction, and CJK East Asian fonts.

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

> **Install `mddocx-native`, not `mddocx`.** An unrelated PyPI project owns the name `mddocx`
> and ships the same `mddocx` package directory and the same `mddocx` command. Installing both
> makes them overwrite each other, so always use the `mddocx-native` distribution name.
> mddocx reports the conflict when it starts, and `mddocx doctor` lists it too.

Verify the installation:

```bash
mddocx --version
mddocx-native --version   # same program; refuses to run when another project overwrote it
mddocx doctor
```

`mddocx doctor` reports the Python version, the dependencies it found, the JavaScript runtime
and math engine it will actually use, and whether another distribution is competing for the
`mddocx` package. It exits with status 2 when something needs attention.

### 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.4.1-py3-none-any.whl
```

On Windows PowerShell, the equivalent command is:

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

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

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

### Install from GitHub

```bash
python -m pip install "git+https://github.com/TasinAhmed2508/mddocx.git@v1.4.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
# Everything except the Node.js runtime
python -m pip install "mddocx-native[all]"

# Include a Node.js runtime so the bundled MathJax engine works without a manual install (~45 MB)
python -m pip install "mddocx-native[mathjax]"

# Individually
python -m pip install "mddocx-native[images]"
python -m pip install "mddocx-native[academic]"   # arbitrary local CSL styles
python -m pip install "mddocx-native[math]"        # included by default; kept for compatibility
```

Equation rendering needs no extra package: a pure-Python engine is always installed, and the
bundled MathJax sidecar is used automatically when a JavaScript runtime is available. Run
`mddocx doctor` to see which engine this machine uses.

### Install troubleshooting

- **`mddocx --version` prints something like `0.5.x`.** The unrelated PyPI project `mddocx` is
  installed as well; the two share one package directory and one command, so whichever was
  installed last wins. Remove both and reinstall this distribution:

  ```bash
  python -m pip uninstall -y mddocx mddocx-native
  python -m pip install --force-reinstall mddocx-native
  ```

  Afterwards use `mddocx-native` (or `python -m mddocx`) so the shared command name cannot be
  taken over again.
- **`mddocx: command not found`.** The Python script directory is not on `PATH`. Every command
  is also available as `python -m mddocx ...`, which needs no `PATH` change.
- **`No matching distribution found for mddocx-native`.** mddocx requires Python 3.11 or newer;
  check `python --version`.
- **`Could not find a version that satisfies the requirement bijoy2unicode`.** That dependency
  is published as a source distribution only, so `--only-binary=:all:` and wheel-only mirrors
  cannot install it. Allow source builds for that package.
- **`mddocx doctor` reports no JavaScript runtime.** Equations still render through the
  pure-Python engine. Install Node.js, or `mddocx-native[mathjax]`, for the MathJax engine.
- **SVG images fail after installing the `images` or `all` extra.** CairoSVG needs a native cairo
  library at run time (not just the Python package). Install it with the usual system package for
  your platform, or convert the SVG to PNG first; every other document feature works without it,
  and `mddocx doctor` reports the exact reason when it is missing.
- **Bangla text looks wrong in Word.** The default `SutonnyMJ` font is not bundled. Install the
  font, or pass `--bengali-font auto` to keep Bangla Unicode while applying an installed
  Unicode Bangla font, or `--bengali-font none` to skip the Bangla output pass entirely.
- **`mddocx` starts the interactive console.** Running it with no arguments on a terminal opens
  the guided console. `mddocx --help` lists every command, and `mddocx FILE.md` converts
  directly.

## 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 document.md --strict-math
    mddocx math-check document.md
    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

Every command is also available as `python -m mddocx ...` when the console script is not on
`PATH`.

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](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/API_STABILITY.md) and can also be inspected with `mddocx api --json`.
The additive compiler-stage mapping and behavioral changes are documented in
[docs/V2_MIGRATION.md](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/V2_MIGRATION.md).

For callers that need the output, diagnostics, and profiling data together, use the staged-v2
compiler service:

    from mddocx import Compiler

    result = Compiler().compile_string("# Report\n\nInline \\(x^2\\).")
    print(result.success, result.diagnostics, result.stats)
    print(result.layout_plan.tables)

The same service exposes `parse_string`, `parse_file`, `normalize`, `plan`, `render`,
`check_string`, `check_file`, `compile_string`, and `compile_file`, so applications can
inspect canonical AST and layout decisions without duplicating compiler internals.

### AI-generated equations

Common inline forms (`\\(...\\)` and `$...$`), display forms (`\\[...\\]` and `$$...$$`),
and `math`, `latex`, or `tex` fenced blocks are converted to editable Word equations. Math-like
text inside code spans and ordinary code fences is preserved as code, and common currency forms
are preserved as text.

When an equation uses syntax that the active math engine cannot convert, mddocx preserves its
source as editable text and emits a `MATH201` warning. Use `--strict-math` when every equation must
be native Word math and conversion should fail on the first unsupported expression. See
`docs/AI_MATH_COMPATIBILITY.md` for the tested compatibility contract.

Run `mddocx math-check document.md` before conversion to see the active math engine and the number
of equations that can be rendered natively. Add `--json` for automation or `--strict` to return
exit code 3 when any equation requires a fallback.

## Language and script support

Markdown and the canonical AST are always Unicode. Script-specific fonts and direction are
applied only to the generated Word XML:

- **Bengali** runs use `SutonnyMJ` by default with Bijoy glyph encoding at the DOCX boundary.
  Set `RenderConfig.fonts.bengali` to a Unicode font (for example `Nirmala UI`) for Unicode
  output, or to `None` to disable the output pass. From the command line, use
  `--bengali-font "Nirmala UI"`, `--bengali-font none`, or `--bengali-font auto`, which uses
  `SutonnyMJ` when it is installed and an installed Unicode Bangla font otherwise. English text
  keeps a Latin font, and mddocx warns (diagnostic `FONT301`) when a configured Bangla font is
  not installed instead of silently emitting unreadable glyphs.
- **Other complex scripts** — Devanagari, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada,
  Malayalam, Sinhala, Thai, Lao, Tibetan, Myanmar, Khmer, Ethiopic, Mongolian, Syriac, Thaana,
  Arabic, and Hebrew — use the `--complex-script-font` slot. Left-to-right scripts stay LTR.
- **Right-to-left** Arabic and Hebrew paragraphs receive Word bidi direction and right alignment
  automatically (`rtl: auto`), or with `--rtl force` / `--rtl off`. Direction and script fonts
  also apply to the title page, abstract, captions, bibliography, headers, footers, and notes.
- **CJK** text — Chinese, Japanese, and Korean, including extension planes — uses the
  `--east-asia-font` slot.

```bash
mddocx report.md -o report.docx --complex-script-font "Nirmala UI" --east-asia-font "Microsoft YaHei"
mddocx arabic-report.md -o arabic-report.docx --rtl force
```

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

- Bounded public HTTP(S) image resources are allowed by default. Failed image syntax becomes a
  clickable fallback; ordinary Markdown links are never downloaded.
- Base64 image data URIs are decoded locally, never sent over the network, and remain subject to
  the configured per-resource size limit and image validation.
- HTTPS image downloads can be explicitly enabled and restricted by domain.
- Use `--block-remote-resources` for a single noninteractive conversion, or
  `--allow-remote-resources` to override a saved shell block for one render.
- 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.

See the [1.4.1 release notes](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/RELEASE_NOTES_1.4.1.md)
for install diagnostics, collision safety, and equation-engine reporting, the
[1.4.0 release notes](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/RELEASE_NOTES_1.4.0.md)
for multilingual script coverage, and the existing
[1.3.0 release notes](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/RELEASE_NOTES_1.3.0.md)
for resilient resources, smart equations, academic references;
[1.2.4 release notes](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/RELEASE_NOTES_1.2.4.md)
cover Base64-image, AI-math, compiler, layout, security-policy, and migration summary.

The compiler stages and system architecture are described in
[docs/ARCHITECTURE.md](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/ARCHITECTURE.md).
The machine-readable supported feature contract is
[docs/feature-matrix.json](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/feature-matrix.json).

The forward plan for usability, performance, and defect prevention is
[docs/ROADMAP.md](https://github.com/TasinAhmed2508/mddocx/blob/main/docs/ROADMAP.md), including the known warts and open quality gaps.

The machine-readable fidelity contract is `docs/feature-matrix.json`; every listed feature links
its accepted syntax, canonical AST, native Word representation, diagnostic behavior, host status,
and tracked regression evidence.

The complete staged engineering program is preserved in
`docs/FIDELITY_FIRST_V2_PLAN.md`; progress and compatibility notes remain additive until a
qualified 2.x release is ready.

Microsoft Word 365 release qualification, including the reusable Windows automation script, is
documented in `docs/WORD365_QA.md`.

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

### Bangla document forms and scanned-document transcriptions

Use `mddocx input.md -o output.docx --theme bengali-document` for compact
Bangla documents (10 pt, single spacing). Bangla output runs use SutonnyMJ
by default, with Unicode-to-Bijoy encoding applied only to Word XML. The output contains editable
Word tables and can be imported into Google Docs. Google Docs may substitute fonts
and reflow pages; verify the imported document before relying on page fidelity.

Plain `text` fences with a box-drawn photo placeholder, at least five labelled
fields, and paired pipe-separated address columns render as native form tables.
Plain-text three-column tables with at least two dashed row separators render as
native tables; continuation lines within a ruled row stay in the same cells.
Programming language fences remain code. Unsupported layouts remain literal code.

Numeric Gemini `[cite: 1]` export tokens outside code are removed by default.
Citation-suffixed matching closing fences are repaired so following paragraphs
are parsed correctly. `--ai-metadata keep` preserves the numeric markers
as text after the repaired closing fence. Markers inside fenced or inline code
remain literal. The converter preserves transcribed values; it does not infer
missing cells or correct discrepancies against a scanned reference.

For layouts that require merged cells, use an explicit `layout-table` YAML fence.
Rows must have equal numbers of string cells; widths are positive relative weights.
Merge coordinates are zero-based `[row, column]` pairs with inclusive endpoints.
Covered cells must be empty, and merge rectangles cannot overlap. This preserves
content and makes scan-specific structure explicit rather than guessing from text.

````markdown
```layout-table
widths: [15, 37, 7, 41]
rows:
  - [Floor, East, West, ""]
  - [Roof, Terrace, "", Owner]
  - [First, Owner, Stairs, Owner]
  - [Ground, Owner, "", Owner]
merges:
  - from: [0, 2]
    to: [0, 3]
  - from: [1, 1]
    to: [1, 2]
  - from: [2, 2]
    to: [3, 2]
```
````

The source Markdown and compiler AST always retain Unicode Bangla. Install
SutonnyMJ on the machine used to open or export DOCX; the font is not bundled.
Mixed English text retains a Latin font. Bijoy-encoded DOCX text depends on
SutonnyMJ and does not have Unicode Bangla copy/search semantics. The PDF
preview provides the intended visual result. `RenderConfig.fonts.bengali`
defaults to `SutonnyMJ`; set it to a Unicode font for Unicode output, or `None`
to disable this output pass. Bijoy conversion uses the pinned MPL-2.0
[bijoy2unicode library](https://github.com/Mad-FOX/bijoy2unicode), with padding
for its end-of-word lookahead and a SutonnyMJ-compatible la-phala glyph fix.
