markitdown-chm 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- markitdown_chm-0.1.0/.github/workflows/ci.yml +41 -0
- markitdown_chm-0.1.0/.github/workflows/publish.yml +46 -0
- markitdown_chm-0.1.0/.gitignore +11 -0
- markitdown_chm-0.1.0/CHANGELOG.md +10 -0
- markitdown_chm-0.1.0/LICENSE +22 -0
- markitdown_chm-0.1.0/PKG-INFO +129 -0
- markitdown_chm-0.1.0/README.md +93 -0
- markitdown_chm-0.1.0/SECURITY.md +22 -0
- markitdown_chm-0.1.0/docs/upstream-gap-analysis.md +53 -0
- markitdown_chm-0.1.0/pyproject.toml +93 -0
- markitdown_chm-0.1.0/src/markitdown_chm/__init__.py +28 -0
- markitdown_chm-0.1.0/src/markitdown_chm/cli.py +64 -0
- markitdown_chm-0.1.0/src/markitdown_chm/converter.py +233 -0
- markitdown_chm-0.1.0/src/markitdown_chm/errors.py +9 -0
- markitdown_chm-0.1.0/src/markitdown_chm/limits.py +23 -0
- markitdown_chm-0.1.0/src/markitdown_chm/model.py +23 -0
- markitdown_chm-0.1.0/src/markitdown_chm/parsing.py +165 -0
- markitdown_chm-0.1.0/src/markitdown_chm/py.typed +1 -0
- markitdown_chm-0.1.0/src/markitdown_chm/rendering.py +140 -0
- markitdown_chm-0.1.0/tests/conftest.py +65 -0
- markitdown_chm-0.1.0/tests/fixtures/NOTICE.md +10 -0
- markitdown_chm-0.1.0/tests/fixtures/sample.chm +0 -0
- markitdown_chm-0.1.0/tests/test_converter.py +104 -0
- markitdown_chm-0.1.0/tests/test_integration.py +18 -0
- markitdown_chm-0.1.0/tests/test_parsing.py +77 -0
- markitdown_chm-0.1.0/tests/test_plugin_and_cli.py +47 -0
- markitdown_chm-0.1.0/tests/test_rendering.py +32 -0
- markitdown_chm-0.1.0/uv.lock +1370 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
test:
|
|
13
|
+
strategy:
|
|
14
|
+
fail-fast: false
|
|
15
|
+
matrix:
|
|
16
|
+
os: [ubuntu-latest, windows-latest, macos-latest]
|
|
17
|
+
python-version: ["3.10", "3.13"]
|
|
18
|
+
runs-on: ${{ matrix.os }}
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v4
|
|
21
|
+
- uses: astral-sh/setup-uv@v6
|
|
22
|
+
with:
|
|
23
|
+
python-version: ${{ matrix.python-version }}
|
|
24
|
+
enable-cache: true
|
|
25
|
+
- run: uv sync --extra dev --locked
|
|
26
|
+
- run: uv run pytest
|
|
27
|
+
|
|
28
|
+
quality:
|
|
29
|
+
runs-on: ubuntu-latest
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
- uses: astral-sh/setup-uv@v6
|
|
33
|
+
with:
|
|
34
|
+
python-version: "3.12"
|
|
35
|
+
enable-cache: true
|
|
36
|
+
- run: uv sync --extra dev --locked
|
|
37
|
+
- run: uv run ruff check .
|
|
38
|
+
- run: uv run ruff format --check .
|
|
39
|
+
- run: uv run mypy
|
|
40
|
+
- run: uv build
|
|
41
|
+
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
build:
|
|
13
|
+
name: Build distributions
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
- uses: astral-sh/setup-uv@v6
|
|
18
|
+
with:
|
|
19
|
+
python-version: "3.12"
|
|
20
|
+
enable-cache: true
|
|
21
|
+
- name: Build sdist and wheel
|
|
22
|
+
run: uv build
|
|
23
|
+
- name: Check metadata
|
|
24
|
+
run: uvx twine check dist/*
|
|
25
|
+
- uses: actions/upload-artifact@v4
|
|
26
|
+
with:
|
|
27
|
+
name: dist
|
|
28
|
+
path: dist/
|
|
29
|
+
if-no-files-found: error
|
|
30
|
+
|
|
31
|
+
publish:
|
|
32
|
+
name: Publish to PyPI
|
|
33
|
+
needs: build
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
environment:
|
|
36
|
+
name: pypi
|
|
37
|
+
url: https://pypi.org/p/markitdown-chm
|
|
38
|
+
permissions:
|
|
39
|
+
id-token: write
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/download-artifact@v4
|
|
42
|
+
with:
|
|
43
|
+
name: dist
|
|
44
|
+
path: dist/
|
|
45
|
+
- name: Publish
|
|
46
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 - 2026-08-28
|
|
4
|
+
|
|
5
|
+
- Add MarkItDown plugin registration and a direct `markitdown-chm` CLI.
|
|
6
|
+
- Preserve CHM project metadata and hierarchical contents order.
|
|
7
|
+
- Add multilingual decoding, internal-link rewriting, and HTML sanitization.
|
|
8
|
+
- Add resource limits for untrusted archives.
|
|
9
|
+
- Add unit, integration, typing, lint, packaging, and multi-platform CI checks.
|
|
10
|
+
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 zyyyz-a
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: markitdown-chm
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Secure CHM-to-Markdown support for Microsoft's MarkItDown
|
|
5
|
+
Project-URL: Homepage, https://github.com/zyyyz-a/markitdown-chm
|
|
6
|
+
Project-URL: Issues, https://github.com/zyyyz-a/markitdown-chm/issues
|
|
7
|
+
Project-URL: Source, https://github.com/zyyyz-a/markitdown-chm
|
|
8
|
+
Project-URL: Upstream issue, https://github.com/microsoft/markitdown/issues/14
|
|
9
|
+
Author: zyyyz-a
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: chm,documentation,markdown,markitdown,migration
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Documentation
|
|
23
|
+
Classifier: Topic :: Text Processing :: Markup
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: beautifulsoup4>=4.12
|
|
26
|
+
Requires-Dist: markdownify>=0.14
|
|
27
|
+
Requires-Dist: markitdown<0.2,>=0.1.3
|
|
28
|
+
Requires-Dist: pylibmspack<0.5,>=0.4.0
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
31
|
+
Requires-Dist: mypy>=1.15; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest>=8.3; extra == 'dev'
|
|
34
|
+
Requires-Dist: ruff>=0.11; extra == 'dev'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# markitdown-chm
|
|
38
|
+
|
|
39
|
+
[](https://github.com/zyyyz-a/markitdown-chm/actions/workflows/ci.yml)
|
|
40
|
+
[](https://www.python.org/)
|
|
41
|
+
[](LICENSE)
|
|
42
|
+
|
|
43
|
+
Secure, cross-platform CHM-to-Markdown support for
|
|
44
|
+
[Microsoft MarkItDown](https://github.com/microsoft/markitdown). It turns legacy
|
|
45
|
+
Compiled HTML Help archives into one structured Markdown document suitable for
|
|
46
|
+
search, documentation migration, and retrieval-augmented generation.
|
|
47
|
+
|
|
48
|
+
This project addresses [microsoft/markitdown#14](https://github.com/microsoft/markitdown/issues/14).
|
|
49
|
+
The issue remains open despite an earlier unmerged attempt. `markitdown-chm`
|
|
50
|
+
uses MarkItDown's supported plugin API and an in-process CHM reader with wheels
|
|
51
|
+
for Windows, macOS, and Linux.
|
|
52
|
+
|
|
53
|
+
## Why this implementation
|
|
54
|
+
|
|
55
|
+
- Preserves the `.hhc` table-of-contents order and nesting instead of sorting
|
|
56
|
+
files alphabetically.
|
|
57
|
+
- Uses the `.hhp` project title, contents file, and default topic when present.
|
|
58
|
+
- Rewrites cross-topic links to stable anchors in the combined Markdown.
|
|
59
|
+
- Detects UTF-8/UTF-16 BOMs and declared HTML charsets, including common CJK
|
|
60
|
+
code pages.
|
|
61
|
+
- Applies explicit limits to input size, member count, topic count, per-topic
|
|
62
|
+
size, and total expanded HTML.
|
|
63
|
+
- Runs without shelling out to `7z`, `hh.exe`, or another executable.
|
|
64
|
+
- Ships a typed API, standalone CLI, automated tests, and reproducible CI.
|
|
65
|
+
|
|
66
|
+
## Install
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install markitdown-chm
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
MarkItDown discovers the package through its `markitdown.plugin` entry point.
|
|
73
|
+
|
|
74
|
+
## Use with MarkItDown
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
markitdown --list-plugins
|
|
78
|
+
markitdown --use-plugins manual.chm -o manual.md
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from markitdown import MarkItDown
|
|
83
|
+
|
|
84
|
+
converter = MarkItDown(enable_plugins=True)
|
|
85
|
+
result = converter.convert("manual.chm")
|
|
86
|
+
print(result.text_content)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The package also provides a direct command for CHM-only workflows:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
markitdown-chm manual.chm -o manual.md
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Safety limits
|
|
96
|
+
|
|
97
|
+
CHM is an archive format and inputs may be untrusted. The defaults reject
|
|
98
|
+
files larger than 512 MiB, archives with more than 20,000 members or 5,000
|
|
99
|
+
HTML topics, individual topics larger than 8 MiB, and more than 256 MiB of
|
|
100
|
+
expanded HTML. The direct CLI exposes flags for lowering these limits.
|
|
101
|
+
|
|
102
|
+
The converter extracts content in memory and removes active HTML content such
|
|
103
|
+
as scripts, embedded objects, frames, and event-handler attributes before
|
|
104
|
+
creating Markdown. See [SECURITY.md](SECURITY.md) for the trust model.
|
|
105
|
+
|
|
106
|
+
## Development
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
uv sync --extra dev
|
|
110
|
+
uv run pytest
|
|
111
|
+
uv run ruff check .
|
|
112
|
+
uv run mypy
|
|
113
|
+
uv build
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
The design rationale and comparison with the stalled upstream implementation
|
|
117
|
+
are documented in [docs/upstream-gap-analysis.md](docs/upstream-gap-analysis.md).
|
|
118
|
+
|
|
119
|
+
## Scope
|
|
120
|
+
|
|
121
|
+
The output is a single Markdown document. Images and other binary resources
|
|
122
|
+
remain referenced by their CHM-relative paths; the plugin does not export an
|
|
123
|
+
asset directory. Password-protected or corrupt archives are rejected.
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
`markitdown-chm` is MIT licensed. Its `pylibmspack` dependency is MIT licensed
|
|
128
|
+
and its wheels bundle `libmspack` under LGPL-2.1; see the dependency's package
|
|
129
|
+
metadata for corresponding source and replacement instructions.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# markitdown-chm
|
|
2
|
+
|
|
3
|
+
[](https://github.com/zyyyz-a/markitdown-chm/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.python.org/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
Secure, cross-platform CHM-to-Markdown support for
|
|
8
|
+
[Microsoft MarkItDown](https://github.com/microsoft/markitdown). It turns legacy
|
|
9
|
+
Compiled HTML Help archives into one structured Markdown document suitable for
|
|
10
|
+
search, documentation migration, and retrieval-augmented generation.
|
|
11
|
+
|
|
12
|
+
This project addresses [microsoft/markitdown#14](https://github.com/microsoft/markitdown/issues/14).
|
|
13
|
+
The issue remains open despite an earlier unmerged attempt. `markitdown-chm`
|
|
14
|
+
uses MarkItDown's supported plugin API and an in-process CHM reader with wheels
|
|
15
|
+
for Windows, macOS, and Linux.
|
|
16
|
+
|
|
17
|
+
## Why this implementation
|
|
18
|
+
|
|
19
|
+
- Preserves the `.hhc` table-of-contents order and nesting instead of sorting
|
|
20
|
+
files alphabetically.
|
|
21
|
+
- Uses the `.hhp` project title, contents file, and default topic when present.
|
|
22
|
+
- Rewrites cross-topic links to stable anchors in the combined Markdown.
|
|
23
|
+
- Detects UTF-8/UTF-16 BOMs and declared HTML charsets, including common CJK
|
|
24
|
+
code pages.
|
|
25
|
+
- Applies explicit limits to input size, member count, topic count, per-topic
|
|
26
|
+
size, and total expanded HTML.
|
|
27
|
+
- Runs without shelling out to `7z`, `hh.exe`, or another executable.
|
|
28
|
+
- Ships a typed API, standalone CLI, automated tests, and reproducible CI.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pip install markitdown-chm
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
MarkItDown discovers the package through its `markitdown.plugin` entry point.
|
|
37
|
+
|
|
38
|
+
## Use with MarkItDown
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
markitdown --list-plugins
|
|
42
|
+
markitdown --use-plugins manual.chm -o manual.md
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from markitdown import MarkItDown
|
|
47
|
+
|
|
48
|
+
converter = MarkItDown(enable_plugins=True)
|
|
49
|
+
result = converter.convert("manual.chm")
|
|
50
|
+
print(result.text_content)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The package also provides a direct command for CHM-only workflows:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
markitdown-chm manual.chm -o manual.md
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Safety limits
|
|
60
|
+
|
|
61
|
+
CHM is an archive format and inputs may be untrusted. The defaults reject
|
|
62
|
+
files larger than 512 MiB, archives with more than 20,000 members or 5,000
|
|
63
|
+
HTML topics, individual topics larger than 8 MiB, and more than 256 MiB of
|
|
64
|
+
expanded HTML. The direct CLI exposes flags for lowering these limits.
|
|
65
|
+
|
|
66
|
+
The converter extracts content in memory and removes active HTML content such
|
|
67
|
+
as scripts, embedded objects, frames, and event-handler attributes before
|
|
68
|
+
creating Markdown. See [SECURITY.md](SECURITY.md) for the trust model.
|
|
69
|
+
|
|
70
|
+
## Development
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
uv sync --extra dev
|
|
74
|
+
uv run pytest
|
|
75
|
+
uv run ruff check .
|
|
76
|
+
uv run mypy
|
|
77
|
+
uv build
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The design rationale and comparison with the stalled upstream implementation
|
|
81
|
+
are documented in [docs/upstream-gap-analysis.md](docs/upstream-gap-analysis.md).
|
|
82
|
+
|
|
83
|
+
## Scope
|
|
84
|
+
|
|
85
|
+
The output is a single Markdown document. Images and other binary resources
|
|
86
|
+
remain referenced by their CHM-relative paths; the plugin does not export an
|
|
87
|
+
asset directory. Password-protected or corrupt archives are rejected.
|
|
88
|
+
|
|
89
|
+
## License
|
|
90
|
+
|
|
91
|
+
`markitdown-chm` is MIT licensed. Its `pylibmspack` dependency is MIT licensed
|
|
92
|
+
and its wheels bundle `libmspack` under LGPL-2.1; see the dependency's package
|
|
93
|
+
metadata for corresponding source and replacement instructions.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Trust model
|
|
4
|
+
|
|
5
|
+
Treat every CHM file as untrusted binary input. `markitdown-chm` parses archives
|
|
6
|
+
with `pylibmspack`, reads only content needed for conversion, and never executes
|
|
7
|
+
HTML, JavaScript, ActiveX, embedded objects, or CHM navigation commands.
|
|
8
|
+
|
|
9
|
+
Before rendering, the converter removes active-content elements and inline
|
|
10
|
+
event-handler attributes. It also enforces bounded reads for the archive and
|
|
11
|
+
each topic, plus limits on member count, topic count, and total HTML bytes.
|
|
12
|
+
|
|
13
|
+
No parser can guarantee safety against every native-library vulnerability. Run
|
|
14
|
+
bulk conversion services with operating-system isolation, current dependencies,
|
|
15
|
+
least privilege, memory/CPU limits, and no access to secrets.
|
|
16
|
+
|
|
17
|
+
## Reporting a vulnerability
|
|
18
|
+
|
|
19
|
+
Please use GitHub's private security-advisory flow for this repository. Include
|
|
20
|
+
a minimal reproducer, affected version, expected impact, and any suggested
|
|
21
|
+
mitigation. Do not attach a malicious CHM to a public issue.
|
|
22
|
+
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Upstream gap analysis
|
|
2
|
+
|
|
3
|
+
## Project selection
|
|
4
|
+
|
|
5
|
+
Microsoft's MarkItDown is a Python document-conversion tool used to prepare
|
|
6
|
+
Office files, PDFs, web pages, and other inputs for text analysis and AI
|
|
7
|
+
workflows. At the time this project was created, the repository had about
|
|
8
|
+
176,800 stars and 12,990 forks and used the MIT license.
|
|
9
|
+
|
|
10
|
+
CHM support is a documented gap: issue
|
|
11
|
+
[#14](https://github.com/microsoft/markitdown/issues/14) is open, labelled
|
|
12
|
+
`enhancement` and `good first issue`, and continued receiving interest in 2026.
|
|
13
|
+
CHM remains relevant for migrating legacy Windows product documentation into
|
|
14
|
+
searchable, model-friendly formats.
|
|
15
|
+
|
|
16
|
+
## Why not build on PR #1367
|
|
17
|
+
|
|
18
|
+
The existing [PR #1367](https://github.com/microsoft/markitdown/pull/1367) has
|
|
19
|
+
remained unmerged. Its own description says the implementation could not be
|
|
20
|
+
tested. A review of the published diff found several production risks:
|
|
21
|
+
|
|
22
|
+
1. It depends on `pychm`, a GPL project in maintenance mode whose latest PyPI
|
|
23
|
+
release was in 2019 and which requires a separately installed native CHMlib.
|
|
24
|
+
2. It assumes CHM APIs while comments in the code acknowledge that those APIs
|
|
25
|
+
may differ.
|
|
26
|
+
3. It sorts every HTML member alphabetically, losing the author's table of
|
|
27
|
+
contents and chapter hierarchy.
|
|
28
|
+
4. It silently catches every per-page exception, which can return apparently
|
|
29
|
+
successful but incomplete documents.
|
|
30
|
+
5. It has no input, member-count, decompression, or page-size limits.
|
|
31
|
+
6. It only tries UTF-8 and Windows-1252, so many multilingual help files are
|
|
32
|
+
decoded incorrectly.
|
|
33
|
+
7. Its linked test vector was added, but the PR description states that the
|
|
34
|
+
converter itself was not successfully tested.
|
|
35
|
+
|
|
36
|
+
## Implemented response
|
|
37
|
+
|
|
38
|
+
This repository takes the supported third-party plugin route described in
|
|
39
|
+
MarkItDown's own documentation. It uses `pylibmspack`, which provides in-process
|
|
40
|
+
CHM parsing, safe extraction primitives, current Python wheels across the three
|
|
41
|
+
major desktop platforms, and explicit read-size limits.
|
|
42
|
+
|
|
43
|
+
The implementation separates archive access, metadata parsing, sanitization,
|
|
44
|
+
topic ordering, link rewriting, rendering, and the MarkItDown adapter. Tests use
|
|
45
|
+
both isolated archive doubles and a redistributable real CHM fixture so that a
|
|
46
|
+
passing build demonstrates actual decompression rather than only mocked logic.
|
|
47
|
+
|
|
48
|
+
## Evidence boundaries
|
|
49
|
+
|
|
50
|
+
This is an independent compatibility plugin. It is not an official Microsoft
|
|
51
|
+
package, does not imply Microsoft sponsorship, and does not claim to resolve the
|
|
52
|
+
upstream issue until maintainers choose to reference or merge an implementation.
|
|
53
|
+
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "markitdown-chm"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Secure CHM-to-Markdown support for Microsoft's MarkItDown"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "zyyyz-a" }]
|
|
13
|
+
keywords = ["chm", "markdown", "markitdown", "documentation", "migration"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Topic :: Documentation",
|
|
25
|
+
"Topic :: Text Processing :: Markup",
|
|
26
|
+
]
|
|
27
|
+
dependencies = [
|
|
28
|
+
"beautifulsoup4>=4.12",
|
|
29
|
+
"markdownify>=0.14",
|
|
30
|
+
"markitdown>=0.1.3,<0.2",
|
|
31
|
+
"pylibmspack>=0.4.0,<0.5",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
dev = [
|
|
36
|
+
"build>=1.2",
|
|
37
|
+
"mypy>=1.15",
|
|
38
|
+
"pytest>=8.3",
|
|
39
|
+
"pytest-cov>=6.0",
|
|
40
|
+
"ruff>=0.11",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.urls]
|
|
44
|
+
Homepage = "https://github.com/zyyyz-a/markitdown-chm"
|
|
45
|
+
Issues = "https://github.com/zyyyz-a/markitdown-chm/issues"
|
|
46
|
+
Source = "https://github.com/zyyyz-a/markitdown-chm"
|
|
47
|
+
"Upstream issue" = "https://github.com/microsoft/markitdown/issues/14"
|
|
48
|
+
|
|
49
|
+
[project.entry-points."markitdown.plugin"]
|
|
50
|
+
chm = "markitdown_chm"
|
|
51
|
+
|
|
52
|
+
[project.scripts]
|
|
53
|
+
markitdown-chm = "markitdown_chm.cli:main"
|
|
54
|
+
|
|
55
|
+
[tool.hatch.build.targets.wheel]
|
|
56
|
+
packages = ["src/markitdown_chm"]
|
|
57
|
+
|
|
58
|
+
[tool.pytest.ini_options]
|
|
59
|
+
addopts = "-ra --strict-markers --cov=markitdown_chm --cov-report=term-missing --cov-fail-under=90"
|
|
60
|
+
testpaths = ["tests"]
|
|
61
|
+
markers = ["integration: exercises a real CHM archive"]
|
|
62
|
+
|
|
63
|
+
[tool.coverage.run]
|
|
64
|
+
branch = true
|
|
65
|
+
|
|
66
|
+
[tool.coverage.report]
|
|
67
|
+
exclude_also = [
|
|
68
|
+
"if TYPE_CHECKING:",
|
|
69
|
+
"if __name__ == .__main__.:",
|
|
70
|
+
]
|
|
71
|
+
|
|
72
|
+
[tool.ruff]
|
|
73
|
+
target-version = "py310"
|
|
74
|
+
line-length = 100
|
|
75
|
+
src = ["src", "tests"]
|
|
76
|
+
|
|
77
|
+
[tool.ruff.lint]
|
|
78
|
+
select = ["E", "F", "I", "B", "UP", "RUF", "SIM", "S"]
|
|
79
|
+
ignore = ["S603"]
|
|
80
|
+
|
|
81
|
+
[tool.ruff.lint.per-file-ignores]
|
|
82
|
+
"tests/**" = ["S101"]
|
|
83
|
+
|
|
84
|
+
[tool.mypy]
|
|
85
|
+
python_version = "3.10"
|
|
86
|
+
strict = true
|
|
87
|
+
packages = ["markitdown_chm"]
|
|
88
|
+
follow_imports = "skip"
|
|
89
|
+
disallow_subclassing_any = false
|
|
90
|
+
|
|
91
|
+
[[tool.mypy.overrides]]
|
|
92
|
+
module = ["bs4.*", "markdownify.*", "pylibmspack.*"]
|
|
93
|
+
ignore_missing_imports = true
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""MarkItDown plugin for Microsoft Compiled HTML Help files."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
from markitdown import PRIORITY_SPECIFIC_FILE_FORMAT, MarkItDown
|
|
8
|
+
|
|
9
|
+
from .converter import ChmConverter
|
|
10
|
+
from .errors import ChmConversionError, ChmSecurityError
|
|
11
|
+
|
|
12
|
+
__all__ = [
|
|
13
|
+
"ChmConversionError",
|
|
14
|
+
"ChmConverter",
|
|
15
|
+
"ChmSecurityError",
|
|
16
|
+
"register_converters",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
__plugin_interface_version__ = 1
|
|
20
|
+
__version__ = "0.1.0"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def register_converters(markitdown: MarkItDown, **_: Any) -> None:
|
|
24
|
+
"""Register CHM conversion with a MarkItDown instance."""
|
|
25
|
+
markitdown.register_converter(
|
|
26
|
+
ChmConverter(),
|
|
27
|
+
priority=PRIORITY_SPECIFIC_FILE_FORMAT,
|
|
28
|
+
)
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""Small direct CLI for CHM-only conversion workflows."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import sys
|
|
7
|
+
from collections.abc import Sequence
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
from markitdown import StreamInfo
|
|
11
|
+
|
|
12
|
+
from .converter import ChmConverter
|
|
13
|
+
from .errors import ChmConversionError
|
|
14
|
+
from .limits import ConversionLimits
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
18
|
+
parser = argparse.ArgumentParser(
|
|
19
|
+
prog="markitdown-chm",
|
|
20
|
+
description="Convert a Microsoft Compiled HTML Help file to Markdown.",
|
|
21
|
+
)
|
|
22
|
+
parser.add_argument("input", type=Path, help="input .chm file")
|
|
23
|
+
parser.add_argument("-o", "--output", type=Path, help="output .md file; defaults to stdout")
|
|
24
|
+
parser.add_argument("--max-input-mib", type=int, default=512)
|
|
25
|
+
parser.add_argument("--max-members", type=int, default=20_000)
|
|
26
|
+
parser.add_argument("--max-topics", type=int, default=5_000)
|
|
27
|
+
parser.add_argument("--max-topic-mib", type=int, default=8)
|
|
28
|
+
parser.add_argument("--max-total-topic-mib", type=int, default=256)
|
|
29
|
+
return parser
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
33
|
+
args = build_parser().parse_args(argv)
|
|
34
|
+
limits = ConversionLimits(
|
|
35
|
+
max_input_bytes=args.max_input_mib * 1024 * 1024,
|
|
36
|
+
max_members=args.max_members,
|
|
37
|
+
max_topics=args.max_topics,
|
|
38
|
+
max_topic_bytes=args.max_topic_mib * 1024 * 1024,
|
|
39
|
+
max_total_topic_bytes=args.max_total_topic_mib * 1024 * 1024,
|
|
40
|
+
)
|
|
41
|
+
converter = ChmConverter(limits=limits)
|
|
42
|
+
try:
|
|
43
|
+
with args.input.open("rb") as stream:
|
|
44
|
+
result = converter.convert(
|
|
45
|
+
stream,
|
|
46
|
+
StreamInfo(
|
|
47
|
+
extension=args.input.suffix,
|
|
48
|
+
filename=args.input.name,
|
|
49
|
+
local_path=str(args.input),
|
|
50
|
+
),
|
|
51
|
+
)
|
|
52
|
+
except (OSError, ValueError, ChmConversionError) as exc:
|
|
53
|
+
print(f"markitdown-chm: {exc}", file=sys.stderr)
|
|
54
|
+
return 2
|
|
55
|
+
|
|
56
|
+
if args.output:
|
|
57
|
+
args.output.write_text(result.text_content, encoding="utf-8", newline="\n")
|
|
58
|
+
else:
|
|
59
|
+
sys.stdout.write(result.text_content)
|
|
60
|
+
return 0
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
if __name__ == "__main__":
|
|
64
|
+
raise SystemExit(main())
|