markitdown-plus 0.2.0__tar.gz

markitdown_plus-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: ["https://www.paypal.me/lamguo"]

markitdown_plus-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Run tests with coverage
+        run: pytest
+      - name: Ruff check
+        run: ruff check .

markitdown_plus-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.env
+.venv/
+venv/
+.DS_Store
+out/
+output/

markitdown_plus-0.2.0/.hermes/TODO.md

@@ -0,0 +1,17 @@
+# MarkItDown Plus Technical Debt
+
+- [x] `--workers` parallel conversion (v0.2.0)
+- [x] `--extract-assets` basic Office/HTML image extraction (v0.2.0)
+- [x] multiple chunk strategies: `heading`, `fixed`, `semantic-lite` (v0.2.0)
+- [x] optional tqdm progress support (v0.2.0)
+- [x] coverage gate target: 85%+ (v0.2.0)
+- [x] property-test scaffolding with optional Hypothesis (v0.2.0)
+- [x] benchmark-test scaffolding with optional pytest-benchmark (v0.2.0)
+- [ ] deeper PDF asset extraction (v0.3.0)
+- [ ] incremental conversion / retry failed (v0.3.0)
+- [ ] table cleanup enhancements (v0.3.0)
+- [ ] MCP server (v0.3.0)
+- [ ] documentation site (v0.3.0)
+- [ ] release automation to PyPI (v0.3.0)
+- [ ] front matter output (v0.3.0)
+- [ ] type-checking CI with pyright or mypy (long-term)

markitdown_plus-0.2.0/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

markitdown_plus-0.2.0/.hypothesis/constants/086764ccb2d66f8a

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\__init__.py
+# hypothesis_version: 6.155.2
+
+['PlusConverter', '__version__', 'chunk_markdown', 'clean_markdown']

markitdown_plus-0.2.0/.hypothesis/constants/110871bc3b4f5e27

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\metadata.py
+# hypothesis_version: 6.155.2
+
+[0.0, 'assets', 'heading', 'markitdown', 'markitdown_version', 'utf-8']

markitdown_plus-0.2.0/.hypothesis/constants/1d68e3aa4dbfdf79

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\errors.py
+# hypothesis_version: 6.155.2
+
+[]

markitdown_plus-0.2.0/.hypothesis/constants/332dd3b2262038d8

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\cli.py
+# hypothesis_version: 6.155.2
+
+[800, '--chunk-size', '--chunk-strategy', '--clean', '--dry-run', '--extract-assets', '--fail-fast', '--model', '--output', '--overlap', '--plugins', '--progress', '--quiet', '--rag', '--recursive', '--types', '--verbose', '--version', '--workers', '-o', '-o output/clean.md', '-o output/report.md', '-r', '-v', 'Input Markdown file.', 'Input file.', 'Output JSONL file.', 'Output directory.', '__main__', 'chunk', 'clean', 'command', 'convert', 'gpt4', 'heading', 'input', 'markitdown-plus', 'single', 'store_true', 'utf-8', 'verbose', 'version']

markitdown_plus-0.2.0/.hypothesis/constants/359268f49f691cc8

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\manifest.py
+# hypothesis_version: 6.155.2
+
+['a', 'created_at', 'failed', 'failed.json', 'failed_records_path', 'files', 'files_truncated', 'manifest.json', 'markitdown-plus', 'output', 'records_path', 'source', 'success', 'tool', 'total', 'utf-8', 'version']

markitdown_plus-0.2.0/.hypothesis/constants/4214944546cf5c7c

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\converter.py
+# hypothesis_version: 6.155.2
+
+['Empty file: %s', 'markdown', 'text_content']

markitdown_plus-0.2.0/.hypothesis/constants/7b4b0b2b153d41d3

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\__about__.py
+# hypothesis_version: 6.155.2
+
+['0.2.0']

markitdown_plus-0.2.0/.hypothesis/constants/8f91968cbf2d23ac

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\utils.py
+# hypothesis_version: 6.155.2
+
+['-', '-+', '-._', 'document', 'ignore', 'utf-8']

markitdown_plus-0.2.0/.hypothesis/constants/92e6eaf999a14c55

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\chunker.py
+# hypothesis_version: 6.155.2
+
+[0.75, 3.5, 4.0, 5.0, 100, 800, 'Apr.', 'Aug.', 'Co.', 'Dec.', 'Dr.', 'Eq.', 'Feb.', 'Fig.', 'Inc.', 'Jan.', 'Jr.', 'Jul.', 'Jun.', 'Ltd.', 'M.D.', 'Mar.', 'Mr.', 'Mrs.', 'Ms.', 'No.', 'Nov.', 'Oct.', 'Ph.D.', 'Prof.', 'Sep.', 'Sept.', 'Sr.', 'St.', 'U.K.', 'U.S.', '[\\u4e00-\\u9fff]', '[^a-z\\s-]', '\\S+', '\\b\\w+\\b', '\\s+', '^#{1,6}\\s+', '^(#{1,6})\\s+(.+?)$', '```', 'a.m.', 'background', 'claude', 'conclusion', 'deepseek', 'document.md', 'e.g.', 'etc.', 'fixed', 'gemini', 'gpt-4', 'gpt-4o', 'gpt4', 'heading', 'https?://\\S+', 'i.e.', 'key takeaway', 'key takeaways', 'methodology', 'next steps', 'p.m.', 'recommendation', 'recommendations', 'results', 'semantic-lite', 'summary', 'utf-8', 'vs.', 'w', '~~~', '。！？']

markitdown_plus-0.2.0/.hypothesis/constants/c4ac8b71d8e3e21f

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\batch.py
+# hypothesis_version: 6.155.2
+
+[800, 10000, '*', '**/*', ',', '.', '.bmp', '.csv', '.doc', '.docx', '.epub', '.gif', '.htm', '.html', '.jpeg', '.jpg', '.json', '.jsonl', '.m4a', '.md', '.mp3', '.pdf', '.png', '.ppt', '.pptx', '.txt', '.wav', '.webp', '.xls', '.xlsx', '.xml', '.zip', '1', 'CI', 'Converting', 'DRY_RUN', 'assets', 'chunks', 'failed', 'failed.jsonl', 'file', 'gpt4', 'heading', 'markdown', 'metadata', 'on', 'true', 'unknown error', 'utf-8', 'workers', 'yes']

markitdown_plus-0.2.0/.hypothesis/constants/c55212a6e09c5e51

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\assets.py
+# hypothesis_version: 6.155.2
+
+['## Extracted Assets', '.', '.bin', '.bmp', '.docx', '.gif', '.htm', '.html', '.jpeg', '.jpg', '.png', '.pptx', '.svg', '.tiff', '.webp', '.xlsx', '/media/', 'data', 'http', 'https', 'ignore', 'image', 'utf-8', 'wb']

markitdown_plus-0.2.0/.hypothesis/constants/e79837f15d416198

@@ -0,0 +1,4 @@
+# file: E:\GIT\markitdown-plus\markitdown-plus-v0.2.0\src\markitdown_plus\cleaner.py
+# hypothesis_version: 6.155.2
+
+['!', '#', '* ', '-', '- ', '.', '/', '> ', '?', '[ \\t]+$', '\\(cid:\\s*\\d+\\)', '\\1 \\2', '\\n{3,}', '\\r\\n?|\\n', '\\s+', '^(#{1,6})([^#\\s].*)$', '^\\d+[.)]\\s+', '^\\d{1,5}$', '```', '|', '~~~', '。', '！', '？']

markitdown_plus-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## v0.2.0 - 2026-06-07
+
+### Added
+
+- Added `--workers` for parallel batch conversion.
+- Added `--progress` with optional tqdm support and CI-safe fallback.
+- Added `--extract-assets` for basic DOCX/PPTX/XLSX/HTML image extraction.
+- Added `assets.py` with asset records and Markdown asset link appending.
+- Added `--chunk-strategy` with `heading`, `fixed`, and `semantic-lite` modes.
+- Added coverage gate target for 85%+ core test coverage.
+- Added optional property-test scaffolding using Hypothesis.
+- Added optional benchmark-test scaffolding using pytest-benchmark.
+- Added `.hermes/TODO.md` technical-debt tracker.
+
+### Changed
+
+- Batch conversion now uses a worker-safe per-file processing path.
+- Metadata now records asset extraction status, asset count, chunk strategy, and asset records.
+- README now documents v0.2.0 features and the roadmap-aligned workflow.
+
+### Notes
+
+- PDF asset extraction is not enabled yet. This remains a v0.3.0+ task because robust PDF image extraction requires heavier dependencies.
+
+## v0.1.2 - 2026-06-07
+
+### Added
+
+- Optional tqdm progress fallback.
+- Large manifest JSONL streaming support.
+- Improved sentence splitting and code-fence-aware paragraph splitting.
+
+## v0.1.1 - 2026-06-07
+
+### Fixed
+
+- Fixed O(n²) manifest counting.
+- Improved Unicode filename safety.
+- Improved page number cleanup and chunk ID uniqueness.
+- Added checkpoint writing and clearer CLI errors.
+
+## v0.1.0 - 2026-06-07
+
+### Added
+
+- Initial MarkItDown Plus alpha release.

markitdown_plus-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lam Guo
+
+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.

markitdown_plus-0.2.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: markitdown-plus
+Version: 0.2.0
+Summary: Batch conversion, asset extraction, and RAG-ready output toolkit for Microsoft MarkItDown.
+Project-URL: Homepage, https://github.com/lamguo/markitdown-plus
+Project-URL: Repository, https://github.com/lamguo/markitdown-plus
+Project-URL: Issues, https://github.com/lamguo/markitdown-plus/issues
+Project-URL: Funding, https://www.paypal.me/lamguo
+Author-email: Lam Guo <lamguo111@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: asset-extraction,batch-conversion,document-conversion,docx-to-markdown,jsonl,llm,markdown,markitdown,microsoft-markitdown,pdf-to-markdown,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: markitdown[all]>=0.1.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: tqdm>=4.66; extra == 'dev'
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.66; extra == 'progress'
+Provides-Extra: quality
+Requires-Dist: hypothesis>=6.100; extra == 'quality'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'quality'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MarkItDown Plus
+
+Batch conversion, asset extraction, RAG-ready Markdown, JSONL chunks, and cleaner AI document pipelines for **Microsoft MarkItDown**.
+
+MarkItDown Plus is an enhancement toolkit built on top of Microsoft MarkItDown. It adds folder conversion, recursive processing, optional parallel workers, Markdown cleanup, multiple chunking strategies, lightweight asset extraction, conversion manifests, and JSONL output for RAG workflows.
+
+> This project is independent and is not affiliated with Microsoft. It is designed as a companion CLI for the Microsoft MarkItDown ecosystem.
+
+## Why MarkItDown Plus?
+
+Microsoft MarkItDown is excellent for converting individual files to Markdown. MarkItDown Plus focuses on the next step: turning many documents into clean, AI-ready project output.
+
+Key features:
+
+- Batch convert files and folders
+- Recursive directory conversion
+- Parallel conversion with `--workers`
+- Optional tqdm progress with `--progress`
+- RAG-ready JSONL chunk export
+- Chunk strategies: `heading`, `fixed`, `semantic-lite`
+- Markdown cleanup for common PDF/document artifacts
+- Basic asset extraction for DOCX / PPTX / XLSX / HTML
+- `manifest.json`, `failed.json`, and large-run JSONL manifest streaming
+- Unicode-safe output filenames
+- PayPal funding link included through GitHub Sponsors/Funding
+
+## Installation
+
+```bash
+pip install markitdown-plus
+```
+
+For progress bars:
+
+```bash
+pip install "markitdown-plus[progress]"
+```
+
+For development tests and coverage:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick Start
+
+Convert a folder:
+
+```bash
+markitdown-plus convert ./docs --output ./out
+```
+
+Convert recursively:
+
+```bash
+markitdown-plus convert ./docs --output ./out --recursive
+```
+
+Convert only specific file types:
+
+```bash
+markitdown-plus convert ./docs --output ./out --types pdf,docx,pptx,xlsx,html,csv
+```
+
+Clean Markdown and export RAG chunks:
+
+```bash
+markitdown-plus convert ./docs --output ./out --clean --rag
+```
+
+Use parallel workers:
+
+```bash
+markitdown-plus convert ./docs --output ./out --recursive --workers 4 --progress
+```
+
+Use auto worker count:
+
+```bash
+markitdown-plus convert ./docs --output ./out --workers 0
+```
+
+Extract assets when supported:
+
+```bash
+markitdown-plus convert ./docs --output ./out --extract-assets
+```
+
+Use a specific chunking strategy:
+
+```bash
+markitdown-plus convert ./docs --output ./out --rag --chunk-strategy semantic-lite
+```
+
+## Output Structure
+
+A normal batch run creates:
+
+```text
+out/
+  markdown/
+    report.md
+  metadata/
+    report.json
+  manifest.json
+```
+
+With RAG enabled:
+
+```text
+out/
+  markdown/
+    report.md
+  chunks/
+    report.jsonl
+  metadata/
+    report.json
+  manifest.json
+```
+
+With asset extraction enabled:
+
+```text
+out/
+  markdown/
+    report.md
+  assets/
+    report_img_001.png
+    report_img_002.jpg
+  metadata/
+    report.json
+  manifest.json
+```
+
+For very large jobs, MarkItDown Plus avoids huge `manifest.json` files by streaming records:
+
+```text
+out/
+  manifest.json
+  manifest-records.jsonl
+  failed.jsonl
+```
+
+## Chunk Strategies
+
+### `heading`
+
+Default. Preserves Markdown heading paths and is best for most structured documents.
+
+```bash
+markitdown-plus convert ./docs -o ./out --rag --chunk-strategy heading
+```
+
+### `fixed`
+
+Creates stable chunk sizes and ignores heading boundaries. Useful for embedding pipelines that prefer consistent lengths.
+
+```bash
+markitdown-plus convert ./docs -o ./out --rag --chunk-strategy fixed
+```
+
+### `semantic-lite`
+
+Dependency-free rule-based topical splitting. It starts new chunks at obvious semantic cues such as headings, summary, conclusion, recommendations, and other section-like paragraphs.
+
+```bash
+markitdown-plus convert ./docs -o ./out --rag --chunk-strategy semantic-lite
+```
+
+## Asset Extraction
+
+`--extract-assets` currently supports lightweight extraction for:
+
+- `.docx`
+- `.pptx`
+- `.xlsx`
+- `.html` / `.htm` local image references
+
+PDF image extraction is intentionally left for a later version because reliable PDF asset extraction requires heavier format-specific dependencies.
+
+When assets are extracted, MarkItDown Plus appends an `Extracted Assets` section to the generated Markdown and records asset metadata in the file-level metadata JSON.
+
+## Single File Commands
+
+Convert one file directly:
+
+```bash
+markitdown-plus single report.pdf -o report.md
+```
+
+Clean an existing Markdown file:
+
+```bash
+markitdown-plus clean dirty.md -o clean.md
+```
+
+Chunk an existing Markdown file:
+
+```bash
+markitdown-plus chunk clean.md -o chunks.jsonl --chunk-strategy fixed
+```
+
+## Development
+
+```bash
+git clone https://github.com/lamguo/markitdown-plus.git
+cd markitdown-plus
+pip install -e ".[dev]"
+pytest
+```
+
+The test configuration includes a coverage gate:
+
+```bash
+pytest --cov=markitdown_plus --cov-fail-under=85
+```
+
+Optional property and benchmark tests are included. They are skipped automatically if `hypothesis` or `pytest-benchmark` is not installed.
+
+## GitHub Topics
+
+Suggested topics for the repository:
+
+```text
+markitdown
+microsoft-markitdown
+markdown
+rag
+llm
+document-conversion
+pdf-to-markdown
+docx-to-markdown
+batch-conversion
+jsonl
+asset-extraction
+ai-tools
+```
+
+## Support This Project
+
+If MarkItDown Plus helps you save time or build better AI document pipelines, you can support development here:
+
+- Star this repository
+- Support via PayPal: https://www.paypal.me/lamguo
+
+Thank you for supporting open-source development.
+
+## License
+
+MIT License.