markdown-docx 0.1.0__tar.gz

markdown_docx-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    env:
+      UV_LINK_MODE: copy
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Run tests
+        run: uv run pytest
+
+  visual-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install LibreOffice and Poppler
+        run: sudo apt-get update && sudo apt-get install -y libreoffice-writer poppler-utils
+
+      - name: Render showcase DOCX
+        run: |
+          mkdir -p .visual
+          uvx --from . markdown-docx sample/showcase.md .visual/showcase.docx
+
+      - name: Convert showcase to PDF
+        run: libreoffice --headless --convert-to pdf --outdir .visual .visual/showcase.docx
+
+      - name: Verify rendered PDF
+        run: pdfinfo .visual/showcase.pdf
+
+  package:
+    needs: [lint, test, visual-smoke]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uv run twine check dist/*
+
+      - name: Smoke-test the wheel
+        shell: bash
+        run: |
+          python -m venv .wheel-smoke
+          .wheel-smoke/bin/python -m pip install dist/*.whl
+          .wheel-smoke/bin/markdown-docx --version
+          .wheel-smoke/bin/markdown-docx --syntax --json
+          echo '# Wheel smoke test' > smoke.md
+          .wheel-smoke/bin/markdown-docx smoke.md smoke.docx
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: distributions
+          path: dist/

markdown_docx-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,109 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    env:
+      UV_LINK_MODE: copy
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Lint, format, and type check
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run mypy
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Verify release tag matches package version
+        if: github.event_name == 'release' && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        shell: bash
+        run: |
+          version_output="$(uv run markdown-docx --version)"
+          package_version="${version_output#markdown-docx }"
+          tag_version="${GITHUB_REF_NAME#v}"
+          test "$package_version" = "$tag_version" || {
+            echo "Package version $package_version does not match release tag $GITHUB_REF_NAME."
+            exit 1
+          }
+
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uv run twine check dist/*
+
+      - name: Smoke-test the wheel
+        shell: bash
+        run: |
+          python -m venv .wheel-smoke
+          .wheel-smoke/bin/python -m pip install dist/*.whl
+          .wheel-smoke/bin/markdown-docx --version
+          .wheel-smoke/bin/markdown-docx --inspect-template --json
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/markdown-docx
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.2

markdown_docx-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+/.mypy_cache/
+/.qa/
+/.pytest_cache/
+/.pytest-tmp/
+/.ruff_cache/
+/.venv/
+/.wheel-smoke/
+/build/
+/dist/
+/**/__pycache__/
+*.egg-info/
+*.py[cod]

markdown_docx-0.1.0/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+This repository contains `markdown-docx`, a strict Python CLI that converts constrained Markdown into editable Word `.docx` files.
+
+## Project identity
+
+- Published package: `markdown-docx`
+- CLI command: `markdown-docx`
+- Python package: `markdown_docx`
+
+## Core rules
+
+- Use only supported public `python-docx` APIs in production code.
+- Never edit OOXML parts directly in production code.
+- Preserve normal Markdown meaning and keep Word metadata in invisible reserved HTML comments.
+- Reject unsupported behavior with stable, line-aware diagnostics.
+- Treat Word sections as layout boundaries. Headings never create sections.
+- Never report a stable page count without a Word-compatible layout engine.
+- Keep parser models independent of `python-docx` objects.
+- Add or update tests whenever behavior changes.
+- Do not use em dashes or semicolons in documentation, messages, or comments.
+
+Tests may inspect generated OOXML read-only for precise assertions.
+
+## Commands
+
+```powershell
+$env:UV_LINK_MODE="copy"
+uv sync --locked --all-groups
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv build
+uv run twine check dist/*
+uvx --refresh --from . markdown-docx sample\showcase.md sample\showcase.docx --force
+```
+
+## Contract files
+
+When the input format changes, update the parser, tests, `README.md`, `src/markdown_docx/assets/syntax.json`, the managed skill text, and the showcase together.

markdown_docx-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Add strict Markdown parsing with invisible YAML directives and line-aware diagnostics.
+- Add editable Word rendering for text, headings, blockquotes, code, mixed nested lists, tables, images, page breaks, and sections.
+- Add blank `.docx` templates, semantic style mapping, font overrides, template inspection, and a packaged default template.
+- Add safe local and remote image handling, JSON automation output, overwrite protection, syntax discovery, and managed agent skill commands.
+- Add a complete test suite, showcase document, CI, package validation, wheel smoke tests, and trusted PyPI publishing.

markdown_docx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Paul Ellis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markdown_docx-0.1.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.5
+Name: markdown-docx
+Version: 0.1.0
+Summary: Convert constrained Markdown documents into editable Word files.
+Project-URL: Homepage, https://github.com/pseudosavant/markdown-docx
+Project-URL: Repository, https://github.com/pseudosavant/markdown-docx
+Project-URL: Issues, https://github.com/pseudosavant/markdown-docx/issues
+Project-URL: Releases, https://github.com/pseudosavant/markdown-docx/releases
+Author: John Paul Ellis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,document,docx,markdown,word
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: markdown-it-py<5,>=3.0
+Requires-Dist: pillow<13,>=10.0
+Requires-Dist: python-docx==1.2.0
+Requires-Dist: pyyaml<7,>=6.0
+Description-Content-Type: text/markdown
+
+# markdown-docx
+
+`markdown-docx` turns constrained Markdown into predictable, editable Word `.docx` files. The Markdown stays readable in normal renderers. Word-specific layout and style settings live in invisible HTML comments.
+
+The format is strict by design. Unsupported input produces a stable, line-aware error instead of an approximate document.
+
+## Prerequisite
+
+The documented workflow uses [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Install `uv` before continuing.
+
+## Quick start with an agent
+
+Install the managed agent skill:
+
+```powershell
+uvx markdown-docx skill install
+```
+
+Then ask an agent to create both the Markdown source and the editable Word output:
+
+> Use $markdown-docx to create a project brief. Keep the source readable as normal Markdown and save the editable DOCX beside it.
+
+The skill teaches the agent how to inspect the format, inspect blank Word templates, render safely, and handle structured results.
+
+## Use the CLI directly
+
+```powershell
+uvx markdown-docx document.md document.docx
+```
+
+When the output path is omitted, the tool writes a `.docx` beside the input Markdown file.
+
+```powershell
+uvx markdown-docx document.md
+```
+
+Inspect the supported syntax:
+
+```powershell
+uvx markdown-docx --syntax
+uvx markdown-docx --syntax --json
+```
+
+## Supported Markdown
+
+Version 0.1.0 supports:
+
+- ATX headings from `#` through `######`
+- Paragraphs and standard soft or hard line breaks
+- Emphasis, strong emphasis, and inline backtick code
+- Fenced code blocks
+- Blockquotes containing paragraphs
+- Ordered and unordered lists, including mixed nesting
+- Pipe tables with inline text formatting
+- Local and remote inline images
+- Standalone images with width and alignment metadata
+
+Links are rejected in 0.1.0. `python-docx` 1.2.0 can read hyperlinks but has no supported public API for creating them. The source alt text for images remains meaningful Markdown content, but the same library release has no public API for embedding it in a Word drawing. A rendered document containing images reports `image_alt_text_not_embedded` in its warning list.
+
+The following syntax is intentionally unsupported:
+
+- Raw HTML and non-reserved HTML comments
+- Setext headings and horizontal rules
+- Indented code blocks
+- Task lists and footnotes
+- Multi-paragraph list items
+- Tables, images, code blocks, or blockquotes nested inside list items
+- Images inside table cells or blockquotes
+- Arbitrary Markdown extensions
+
+## Invisible Word metadata
+
+Only HTML comments beginning with `markdown-docx` are accepted. All other HTML is an error.
+
+Document metadata may appear once. It must be the first non-whitespace content:
+
+```markdown
+<!-- markdown-docx
+document:
+  page_size: letter
+  orientation: portrait
+  margins:
+    top: 1in
+    right: 1in
+    bottom: 1in
+    left: 1in
+  styles:
+    paragraph: Normal
+    headings:
+      1: Heading 1
+      2: Heading 2
+      3: Heading 3
+      4: Heading 4
+      5: Heading 5
+      6: Heading 6
+    blockquote: Quote
+    code_block: Code Block
+    ordered_list:
+      - List Number
+      - List Number 2
+      - List Number 3
+    unordered_list:
+      - List Bullet
+      - List Bullet 2
+      - List Bullet 3
+    table: Table Grid
+  fonts:
+    body: Calibri
+    headings: Calibri
+    monospace: Consolas
+-->
+
+# Project brief
+
+This remains ordinary Markdown.
+```
+
+Metadata uses strict YAML. Duplicate keys, unknown keys, invalid types, unitless lengths, and misplaced comments are errors.
+
+### Page sizes and margins
+
+Named page sizes are `letter`, `legal`, and `a4`. Custom page sizes use nominal portrait dimensions. The width must not exceed the height.
+
+```markdown
+<!-- markdown-docx
+document:
+  page_size:
+    width: 7in
+    height: 10in
+  orientation: portrait
+  margins:
+    top: 0.75in
+    right: 0.75in
+    bottom: 0.75in
+    left: 0.75in
+-->
+```
+
+Lengths accept `in`, `cm`, `mm`, and `pt`. Margins must leave a positive usable page area.
+
+### Sections
+
+A section directive starts a next-page Word section before the following content block:
+
+```markdown
+<!-- markdown-docx
+section:
+  page_size: letter
+  orientation: landscape
+  margins:
+    top: 0.75in
+    right: 0.75in
+    bottom: 0.75in
+    left: 0.75in
+-->
+
+## Landscape analysis
+```
+
+Each section starts from the document defaults and applies its own overrides. It does not inherit omitted values from the preceding section. Reset to the document defaults with:
+
+```markdown
+<!-- markdown-docx
+section: default
+-->
+```
+
+Headings never create sections.
+
+### Page breaks
+
+Insert a page break before the next content block:
+
+```markdown
+<!-- markdown-docx: page-break -->
+
+## Appendix
+```
+
+A page break does not create a new section.
+
+## Templates and styles
+
+A custom template must be a blank `.docx` formatting template. `.dotx` is not supported. The template may define styles, theme data, fonts, numbering definitions, and section defaults. It must not contain:
+
+- Non-whitespace body text
+- Body tables
+- Body images or drawings
+- Nonempty headers or footers
+
+Inspect a template before writing Markdown that refers to its style names:
+
+```powershell
+uvx markdown-docx --inspect-template --template formatting.docx
+uvx markdown-docx --list-styles --template formatting.docx
+uvx markdown-docx --list-table-styles --template formatting.docx
+```
+
+Render with the template:
+
+```powershell
+uvx markdown-docx report.md report.docx --template formatting.docx
+```
+
+The template remains unchanged. When no template is supplied, the packaged blank template provides every default style.
+
+The Markdown metadata maps semantic constructs to paragraph and table style names. Each configured style must exist and must have the correct Word style type. Body and heading font overrides modify the mapped paragraph styles. The monospace override applies to code blocks and inline code. Sizes, colors, spacing, borders, and other typography remain owned by the template.
+
+## Lists
+
+Apply one Word paragraph style per list type and nesting depth:
+
+```yaml
+styles:
+  ordered_list:
+    - List Number
+    - List Number 2
+    - List Number 3
+  unordered_list:
+    - List Bullet
+    - List Bullet 2
+    - List Bullet 3
+```
+
+Mixed nested lists select ordered or unordered styles independently at every depth. A list deeper than the configured style array is an error. Ordered lists must begin with `1`. Restart controls and arbitrary start values are not supported.
+
+## Tables
+
+Standard pipe tables become editable Word tables. Put optional table metadata immediately before the table:
+
+```markdown
+<!-- markdown-docx
+table:
+  style: Table Grid
+  alignment: center
+  width: page
+  column_widths: [3, 1, 1]
+-->
+
+| Item | Count | Price |
+| --- | ---: | ---: |
+| Widget | 2 | $10 |
+```
+
+The first Markdown row is the semantic header row. Cell alignment follows the Markdown delimiter row. `column_widths` contains positive ratios and must match the column count. `width: page` uses the active section's usable width. `width: auto` lets Word size the table unless ratios are supplied.
+
+Merged cells, nested tables, fixed row heights, repeated-header controls, and per-cell border or fill metadata are not supported.
+
+## Images
+
+Relative paths resolve from the Markdown file's directory:
+
+```markdown
+Text before ![Status icon](images/status.png) text after.
+```
+
+Put metadata immediately before a standalone image:
+
+```markdown
+<!-- markdown-docx
+image:
+  width: 40%
+  alignment: center
+-->
+![Architecture](images/architecture.png)
+```
+
+Widths accept `in`, `cm`, `mm`, `pt`, or a percentage of the active section's usable width. Images preserve aspect ratio. Natural-size images are clamped to the usable width. An explicit physical width that exceeds the usable width is an error.
+
+HTTP and HTTPS images use timeouts, a 25 MiB download limit, content-type validation, a 50 megapixel decode limit, and one download per unique URL. Reject remote images for offline builds or untrusted input:
+
+```powershell
+uvx markdown-docx report.md --no-remote-images
+```
+
+## Automation and safety
+
+Use `--json` for one complete machine-readable result:
+
+```powershell
+uvx markdown-docx report.md report.docx --json
+```
+
+A successful result contains the input path, output path, template identifier, section count, and warnings. It does not report a page count. DOCX files do not have a reliable intrinsic page count until a compatible layout engine paginates them.
+
+The CLI refuses to overwrite an existing output. Add `--force` only when replacement is intended:
+
+```powershell
+uvx markdown-docx report.md report.docx --force --json
+```
+
+For stdin, provide both an output path and a base directory:
+
+```powershell
+Get-Content report.md | uvx markdown-docx --input - --output report.docx --base-dir .
+```
+
+Exit codes:
+
+| Code | Meaning |
+| ---: | --- |
+| `0` | Success |
+| `2` | Usage or input error |
+| `3` | Markdown or metadata parse error |
+| `4` | Template or style error |
+| `5` | Image or asset error |
+| `6` | Unsupported Markdown or feature |
+| `7` | DOCX rendering error |
+| `8` | Unexpected internal error |
+
+## Complete example
+
+See [the showcase Markdown](sample/showcase.md). It opens with an illustrated three-dog story, then exercises supported text, list, table, image, page-break, and section behavior in a dedicated capability lab. Regenerate it from a repository checkout:
+
+```powershell
+uvx --refresh --from . markdown-docx sample\showcase.md sample\showcase.docx --force
+```
+
+## Public API boundary
+
+Production code uses only documented public `python-docx` APIs. It does not write OOXML directly and does not call private library members. Tests may inspect generated package XML read-only. The complete capability decision record is in [docs/public-api-capabilities.md](docs/public-api-capabilities.md).
+
+Word is the primary compatibility target. LibreOffice Writer is used as a visual smoke-test engine. Differences in pagination or font metrics can occur between layout engines.
+
+## Development
+
+```powershell
+$env:UV_LINK_MODE="copy"
+uv sync --locked --all-groups
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+Build and validate distributions:
+
+```powershell
+uv build
+uv run twine check dist/*
+```