markitdown-chm 0.1.0__py3-none-any.whl

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.
@@ -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
+ )
markitdown_chm/cli.py ADDED
@@ -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())
@@ -0,0 +1,233 @@
1
+ """MarkItDown adapter and bounded CHM conversion pipeline."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import io
6
+ import posixpath
7
+ from collections.abc import Mapping
8
+ from typing import Any, BinaryIO, cast
9
+
10
+ from markitdown import (
11
+ DocumentConverter,
12
+ DocumentConverterResult,
13
+ StreamInfo,
14
+ )
15
+ from pylibmspack import ChmArchive, ChmError
16
+
17
+ from .errors import ChmConversionError, ChmSecurityError
18
+ from .limits import ConversionLimits
19
+ from .model import ProjectMetadata, Topic
20
+ from .parsing import (
21
+ decode_text,
22
+ normalize_member_path,
23
+ parse_project,
24
+ parse_toc,
25
+ select_topics,
26
+ stable_anchor,
27
+ )
28
+ from .rendering import combine_topics, render_topic
29
+
30
+ CHM_MAGIC = b"ITSF"
31
+ CHM_EXTENSIONS = {".chm"}
32
+ CHM_MIME_TYPES = {"application/vnd.ms-htmlhelp", "application/x-chm"}
33
+
34
+
35
+ class ChmConverter(DocumentConverter):
36
+ """Convert a CHM archive to one ordered Markdown document."""
37
+
38
+ def __init__(
39
+ self,
40
+ *,
41
+ limits: ConversionLimits | None = None,
42
+ ) -> None:
43
+ self.limits = limits or ConversionLimits()
44
+
45
+ def accepts(
46
+ self,
47
+ file_stream: BinaryIO,
48
+ stream_info: StreamInfo,
49
+ **_: Any,
50
+ ) -> bool:
51
+ """Recognize CHM by magic bytes, extension, or registered MIME type."""
52
+ if _peek(file_stream, len(CHM_MAGIC)) == CHM_MAGIC:
53
+ return True
54
+ extension = (stream_info.extension or "").casefold()
55
+ mimetype = (stream_info.mimetype or "").split(";", 1)[0].strip().casefold()
56
+ return extension in CHM_EXTENSIONS or mimetype in CHM_MIME_TYPES
57
+
58
+ def convert(
59
+ self,
60
+ file_stream: BinaryIO,
61
+ stream_info: StreamInfo,
62
+ **_: Any,
63
+ ) -> DocumentConverterResult:
64
+ """Read, validate, order, sanitize, and render a CHM stream."""
65
+ data = _bounded_read(file_stream, self.limits.max_input_bytes)
66
+ if not data.startswith(CHM_MAGIC):
67
+ raise ChmConversionError(
68
+ "Input is labelled as CHM but does not start with ITSF magic bytes"
69
+ )
70
+
71
+ try:
72
+ archive = ChmArchive.from_bytes(data)
73
+ raw_entries = archive.files(include_system=True)
74
+ except ChmError as exc:
75
+ raise ChmConversionError(f"Unable to open CHM archive: {exc}") from exc
76
+
77
+ if len(raw_entries) > self.limits.max_members:
78
+ raise ChmSecurityError(
79
+ f"CHM contains {len(raw_entries)} members; limit is {self.limits.max_members}"
80
+ )
81
+
82
+ raw_by_normalized: dict[str, str] = {}
83
+ sizes: dict[str, int] = {}
84
+ for entry in raw_entries:
85
+ normalized = normalize_member_path(entry["name"])
86
+ if not normalized:
87
+ continue
88
+ key = normalized.casefold()
89
+ raw_by_normalized.setdefault(key, entry["name"])
90
+ sizes.setdefault(key, int(entry["size"]))
91
+
92
+ member_lookup = {key: normalize_member_path(raw) for key, raw in raw_by_normalized.items()}
93
+ project = self._load_project(archive, raw_by_normalized, sizes)
94
+ toc = self._load_toc(archive, project, raw_by_normalized, sizes, member_lookup)
95
+ topics = select_topics(member_lookup.values(), toc, project.default_topic)
96
+ if not topics:
97
+ raise ChmConversionError("CHM archive contains no supported HTML topics")
98
+ if len(topics) > self.limits.max_topics:
99
+ raise ChmSecurityError(
100
+ f"CHM contains {len(topics)} HTML topics; limit is {self.limits.max_topics}"
101
+ )
102
+
103
+ anchors = {topic.path.casefold(): stable_anchor(topic.path) for topic in topics}
104
+ rendered: list[tuple[str, str]] = []
105
+ total_bytes = 0
106
+ for topic in topics:
107
+ key = topic.path.casefold()
108
+ declared_size = sizes.get(key, 0)
109
+ if declared_size > self.limits.max_topic_bytes:
110
+ raise ChmSecurityError(
111
+ f"CHM topic {topic.path!r} is {declared_size} bytes; "
112
+ f"limit is {self.limits.max_topic_bytes}"
113
+ )
114
+ payload = self._read_member(archive, raw_by_normalized[key], topic.path)
115
+ total_bytes += len(payload)
116
+ if total_bytes > self.limits.max_total_topic_bytes:
117
+ raise ChmSecurityError(
118
+ "Expanded HTML exceeds total limit of "
119
+ f"{self.limits.max_total_topic_bytes} bytes"
120
+ )
121
+ rendered.append(render_topic(decode_text(payload), topic, anchors, member_lookup))
122
+
123
+ title = (
124
+ project.title
125
+ or _first_meaningful_title(topics, rendered)
126
+ or _stream_title(stream_info)
127
+ or "CHM document"
128
+ )
129
+ return DocumentConverterResult(
130
+ markdown=combine_topics(topics, rendered, title),
131
+ title=title,
132
+ )
133
+
134
+ def convert_bytes(
135
+ self,
136
+ data: bytes,
137
+ *,
138
+ filename: str = "document.chm",
139
+ ) -> DocumentConverterResult:
140
+ """Convenience API for callers that already hold the CHM in memory."""
141
+ return self.convert(
142
+ io.BytesIO(data),
143
+ StreamInfo(
144
+ mimetype="application/vnd.ms-htmlhelp",
145
+ extension=".chm",
146
+ filename=filename,
147
+ ),
148
+ )
149
+
150
+ def _load_project(
151
+ self,
152
+ archive: ChmArchive,
153
+ raw_by_normalized: Mapping[str, str],
154
+ sizes: Mapping[str, int],
155
+ ) -> ProjectMetadata:
156
+ candidates = sorted(
157
+ (key for key in raw_by_normalized if key.endswith(".hhp")),
158
+ key=str.casefold,
159
+ )
160
+ if not candidates:
161
+ return ProjectMetadata()
162
+ key = candidates[0]
163
+ if sizes.get(key, 0) > self.limits.max_topic_bytes:
164
+ raise ChmSecurityError("CHM project metadata exceeds the per-topic size limit")
165
+ return parse_project(self._read_member(archive, raw_by_normalized[key], key))
166
+
167
+ def _load_toc(
168
+ self,
169
+ archive: ChmArchive,
170
+ project: ProjectMetadata,
171
+ raw_by_normalized: Mapping[str, str],
172
+ sizes: Mapping[str, int],
173
+ member_lookup: Mapping[str, str],
174
+ ) -> list[Topic]:
175
+ preferred = project.contents_file.casefold() if project.contents_file else None
176
+ candidates = sorted(
177
+ (key for key in raw_by_normalized if key.endswith(".hhc")),
178
+ key=lambda key: (key != preferred, key),
179
+ )
180
+ if not candidates:
181
+ return []
182
+ key = candidates[0]
183
+ if sizes.get(key, 0) > self.limits.max_topic_bytes:
184
+ raise ChmSecurityError("CHM table of contents exceeds the per-topic size limit")
185
+ return parse_toc(
186
+ self._read_member(archive, raw_by_normalized[key], key),
187
+ member_lookup,
188
+ )
189
+
190
+ def _read_member(self, archive: ChmArchive, raw_path: str, display_path: str) -> bytes:
191
+ try:
192
+ return cast(
193
+ bytes,
194
+ archive.read(raw_path, max_size=self.limits.max_topic_bytes),
195
+ )
196
+ except ChmError as exc:
197
+ raise ChmConversionError(f"Unable to read CHM member {display_path!r}: {exc}") from exc
198
+
199
+
200
+ def _bounded_read(stream: BinaryIO, limit: int) -> bytes:
201
+ payload = stream.read(limit + 1)
202
+ if len(payload) > limit:
203
+ raise ChmSecurityError(f"CHM input exceeds the configured {limit}-byte limit")
204
+ return payload
205
+
206
+
207
+ def _peek(stream: BinaryIO, size: int) -> bytes:
208
+ try:
209
+ position = stream.tell()
210
+ data = stream.read(size)
211
+ stream.seek(position)
212
+ return data
213
+ except (AttributeError, OSError, io.UnsupportedOperation):
214
+ return b""
215
+
216
+
217
+ def _stream_title(stream_info: StreamInfo) -> str | None:
218
+ value = stream_info.filename or stream_info.local_path
219
+ if not value:
220
+ return None
221
+ name = posixpath.basename(value.replace("\\", "/"))
222
+ return posixpath.splitext(name)[0] or None
223
+
224
+
225
+ def _first_meaningful_title(
226
+ topics: list[Topic],
227
+ rendered: list[tuple[str, str]],
228
+ ) -> str | None:
229
+ for topic, (_, title) in zip(topics, rendered, strict=True):
230
+ basename = posixpath.basename(topic.path)
231
+ if title and title.casefold() not in {basename.casefold(), topic.path.casefold()}:
232
+ return title
233
+ return None
@@ -0,0 +1,9 @@
1
+ """Public exceptions raised by markitdown-chm."""
2
+
3
+
4
+ class ChmConversionError(RuntimeError):
5
+ """The CHM archive could not be decoded into useful Markdown."""
6
+
7
+
8
+ class ChmSecurityError(ChmConversionError):
9
+ """The archive exceeded a configured resource or safety limit."""
@@ -0,0 +1,23 @@
1
+ """Resource limits for processing untrusted legacy archives."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, fields
6
+
7
+
8
+ @dataclass(frozen=True, slots=True)
9
+ class ConversionLimits:
10
+ """Hard limits applied before and during CHM expansion."""
11
+
12
+ max_input_bytes: int = 512 * 1024 * 1024
13
+ max_members: int = 20_000
14
+ max_topics: int = 5_000
15
+ max_topic_bytes: int = 8 * 1024 * 1024
16
+ max_total_topic_bytes: int = 256 * 1024 * 1024
17
+
18
+ def __post_init__(self) -> None:
19
+ for field in fields(self):
20
+ name = field.name
21
+ value = getattr(self, name)
22
+ if value <= 0:
23
+ raise ValueError(f"{name} must be greater than zero")
@@ -0,0 +1,23 @@
1
+ """Small immutable value objects used during conversion."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+
8
+ @dataclass(frozen=True, slots=True)
9
+ class Topic:
10
+ """One HTML topic in a CHM table of contents."""
11
+
12
+ path: str
13
+ title: str
14
+ depth: int = 0
15
+
16
+
17
+ @dataclass(frozen=True, slots=True)
18
+ class ProjectMetadata:
19
+ """Relevant fields from a CHM project file."""
20
+
21
+ title: str | None = None
22
+ contents_file: str | None = None
23
+ default_topic: str | None = None
@@ -0,0 +1,165 @@
1
+ """Parsers for the text-based metadata stored inside CHM archives."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import codecs
6
+ import hashlib
7
+ import html
8
+ import posixpath
9
+ import re
10
+ from collections.abc import Iterable, Mapping
11
+
12
+ from bs4 import BeautifulSoup, Tag
13
+
14
+ from .model import ProjectMetadata, Topic
15
+
16
+ _META_CHARSET = re.compile(
17
+ rb"<meta\s+[^>]*(?:charset\s*=\s*[\"']?\s*([^\s\"'/>;]+)|"
18
+ rb"content\s*=\s*[\"'][^\"']*charset\s*=\s*([^\s\"'/>;]+))",
19
+ re.IGNORECASE,
20
+ )
21
+ _WINDOWS_CODE_PAGE = re.compile(r"^(?:windows-|cp-?)(\d+)$", re.IGNORECASE)
22
+ _HTML_SUFFIXES = (".htm", ".html", ".xhtml", ".shtml")
23
+
24
+
25
+ def normalize_member_path(value: str) -> str:
26
+ """Return a comparable CHM member path without allowing traversal."""
27
+ cleaned = html.unescape(value).split("#", 1)[0].split("?", 1)[0]
28
+ cleaned = cleaned.replace("\\", "/").lstrip("/")
29
+ normalized = posixpath.normpath(cleaned)
30
+ if normalized in {"", "."} or normalized == ".." or normalized.startswith("../"):
31
+ return ""
32
+ return normalized
33
+
34
+
35
+ def decode_text(data: bytes) -> str:
36
+ """Decode HTML/project bytes using BOM and declared-charset evidence first."""
37
+ if data.startswith(codecs.BOM_UTF8):
38
+ return data.decode("utf-8-sig")
39
+ if data.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
40
+ return data.decode("utf-16")
41
+
42
+ declared = _declared_charset(data[:8192])
43
+ candidates = [declared, "utf-8", "gb18030", "cp1252"]
44
+ for encoding in candidates:
45
+ if not encoding:
46
+ continue
47
+ try:
48
+ return data.decode(encoding)
49
+ except (LookupError, UnicodeDecodeError):
50
+ continue
51
+ return data.decode("utf-8", errors="replace")
52
+
53
+
54
+ def parse_project(data: bytes) -> ProjectMetadata:
55
+ """Parse the small INI-like `.hhp` project file."""
56
+ values: dict[str, str] = {}
57
+ in_options = False
58
+ for raw_line in decode_text(data).splitlines():
59
+ line = raw_line.strip().lstrip("\ufeff")
60
+ if line.startswith("[") and line.endswith("]"):
61
+ in_options = line.casefold() == "[options]"
62
+ continue
63
+ if not in_options or "=" not in line:
64
+ continue
65
+ key, value = line.split("=", 1)
66
+ values[key.strip().casefold()] = value.strip().strip('"')
67
+ return ProjectMetadata(
68
+ title=values.get("title"),
69
+ contents_file=normalize_member_path(values.get("contents file", "")) or None,
70
+ default_topic=normalize_member_path(values.get("default topic", "")) or None,
71
+ )
72
+
73
+
74
+ def parse_toc(data: bytes, member_lookup: Mapping[str, str]) -> list[Topic]:
75
+ """Parse an HTML Help contents file while preserving its nested order."""
76
+ soup = BeautifulSoup(decode_text(data), "html.parser")
77
+ topics: list[Topic] = []
78
+ seen: set[str] = set()
79
+ for obj in soup.find_all("object"):
80
+ if not isinstance(obj, Tag):
81
+ continue
82
+ params = {
83
+ str(param.get("name", "")).casefold(): str(param.get("value", "")).strip()
84
+ for param in obj.find_all("param", recursive=False)
85
+ if isinstance(param, Tag)
86
+ }
87
+ path = normalize_member_path(params.get("local", ""))
88
+ actual = member_lookup.get(path.casefold())
89
+ if not actual or actual.casefold() in seen or not is_html_member(actual):
90
+ continue
91
+ title = params.get("name", "").strip() or posixpath.basename(actual)
92
+ topics.append(Topic(path=actual, title=title, depth=_list_depth(obj)))
93
+ seen.add(actual.casefold())
94
+ return topics
95
+
96
+
97
+ def select_topics(
98
+ members: Iterable[str],
99
+ toc_topics: Iterable[Topic],
100
+ default_topic: str | None,
101
+ ) -> list[Topic]:
102
+ """Keep TOC order, then append HTML pages omitted by the TOC deterministically."""
103
+ html_members = sorted(
104
+ (path for path in members if is_html_member(path) and not is_system_member(path)),
105
+ key=str.casefold,
106
+ )
107
+ by_key = {path.casefold(): path for path in html_members}
108
+ ordered: list[Topic] = []
109
+ seen: set[str] = set()
110
+
111
+ for topic in toc_topics:
112
+ key = topic.path.casefold()
113
+ if key not in seen:
114
+ ordered.append(topic)
115
+ seen.add(key)
116
+
117
+ if default_topic:
118
+ actual = by_key.get(default_topic.casefold())
119
+ if actual and actual.casefold() not in seen:
120
+ ordered.insert(0, Topic(path=actual, title=posixpath.basename(actual)))
121
+ seen.add(actual.casefold())
122
+
123
+ for path in html_members:
124
+ key = path.casefold()
125
+ if key not in seen:
126
+ ordered.append(Topic(path=path, title=posixpath.basename(path)))
127
+ seen.add(key)
128
+ return ordered
129
+
130
+
131
+ def stable_anchor(path: str) -> str:
132
+ """Create a deterministic, collision-resistant anchor for a CHM topic."""
133
+ stem = posixpath.splitext(posixpath.basename(path))[0].casefold()
134
+ slug = re.sub(r"[^a-z0-9\u4e00-\u9fff]+", "-", stem).strip("-") or "topic"
135
+ digest = hashlib.sha1(path.casefold().encode("utf-8"), usedforsecurity=False).hexdigest()[:8]
136
+ return f"chm-{slug}-{digest}"
137
+
138
+
139
+ def is_html_member(path: str) -> bool:
140
+ return normalize_member_path(path).casefold().endswith(_HTML_SUFFIXES)
141
+
142
+
143
+ def is_system_member(path: str) -> bool:
144
+ cleaned = path.replace("\\", "/").lstrip("/")
145
+ return cleaned.startswith(("#", "::"))
146
+
147
+
148
+ def _declared_charset(head: bytes) -> str | None:
149
+ match = _META_CHARSET.search(head)
150
+ if not match:
151
+ return None
152
+ raw = next((group for group in match.groups() if group), b"")
153
+ value = raw.decode("ascii", errors="ignore").strip().casefold()
154
+ code_page = _WINDOWS_CODE_PAGE.match(value)
155
+ if code_page:
156
+ value = f"cp{code_page.group(1)}"
157
+ try:
158
+ codecs.lookup(value)
159
+ except LookupError:
160
+ return None
161
+ return value
162
+
163
+
164
+ def _list_depth(node: Tag) -> int:
165
+ return max(0, sum(1 for parent in node.parents if getattr(parent, "name", None) == "ul") - 1)
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,140 @@
1
+ """Turn ordered CHM HTML topics into a single safe Markdown document."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import posixpath
6
+ import re
7
+ from collections.abc import Mapping, Sequence
8
+ from urllib.parse import unquote, urlsplit
9
+
10
+ from bs4 import BeautifulSoup, Tag
11
+ from markdownify import markdownify
12
+
13
+ from .model import Topic
14
+ from .parsing import normalize_member_path, stable_anchor
15
+
16
+ _ACTIVE_ELEMENTS = (
17
+ "script",
18
+ "style",
19
+ "noscript",
20
+ "iframe",
21
+ "frame",
22
+ "frameset",
23
+ "object",
24
+ "embed",
25
+ "applet",
26
+ "form",
27
+ "button",
28
+ "input",
29
+ "select",
30
+ "textarea",
31
+ )
32
+ _CHM_SCHEME_PATH = re.compile(r"^(?:mk:@MSITStore:|ms-its:).*?::/?(.*)$", re.IGNORECASE)
33
+
34
+
35
+ def render_topic(
36
+ html_text: str,
37
+ topic: Topic,
38
+ anchors: Mapping[str, str],
39
+ member_lookup: Mapping[str, str],
40
+ ) -> tuple[str, str]:
41
+ """Sanitize and render one HTML topic, returning Markdown and its best title."""
42
+ soup = BeautifulSoup(html_text, "html.parser")
43
+ title = _best_title(soup, topic.title)
44
+ for element in soup.find_all(_ACTIVE_ELEMENTS):
45
+ element.decompose()
46
+ for element in soup.find_all(True):
47
+ if not isinstance(element, Tag):
48
+ continue
49
+ for attribute in list(element.attrs):
50
+ if attribute.casefold().startswith("on") or attribute.casefold() == "srcdoc":
51
+ del element.attrs[attribute]
52
+ _rewrite_links(soup, topic.path, anchors, member_lookup)
53
+ _demote_headings(soup)
54
+
55
+ body = soup.body or soup
56
+ for title_node in body.find_all("title"):
57
+ title_node.decompose()
58
+ rendered = markdownify(str(body), heading_style="ATX", bullets="-").strip()
59
+ return rendered, title
60
+
61
+
62
+ def combine_topics(
63
+ topics: Sequence[Topic],
64
+ rendered: Sequence[tuple[str, str]],
65
+ document_title: str,
66
+ ) -> str:
67
+ """Combine rendered topics with a hierarchical, linkable table of contents."""
68
+ lines = [f"# {document_title}", "", "## Contents", ""]
69
+ for topic, (_, title) in zip(topics, rendered, strict=True):
70
+ indent = " " * min(topic.depth, 10)
71
+ lines.append(f"{indent}- [{_escape_link_text(title)}](#{stable_anchor(topic.path)})")
72
+
73
+ for topic, (content, title) in zip(topics, rendered, strict=True):
74
+ lines.extend(
75
+ [
76
+ "",
77
+ "---",
78
+ "",
79
+ f'<a id="{stable_anchor(topic.path)}"></a>',
80
+ "",
81
+ f"## {title}",
82
+ "",
83
+ f"_CHM source: `{topic.path}`_",
84
+ "",
85
+ content,
86
+ ]
87
+ )
88
+ return "\n".join(lines).strip() + "\n"
89
+
90
+
91
+ def _rewrite_links(
92
+ soup: BeautifulSoup,
93
+ current_path: str,
94
+ anchors: Mapping[str, str],
95
+ member_lookup: Mapping[str, str],
96
+ ) -> None:
97
+ current_dir = posixpath.dirname(current_path)
98
+ for link in soup.find_all("a", href=True):
99
+ if not isinstance(link, Tag):
100
+ continue
101
+ href = str(link.get("href", "")).strip()
102
+ lowered = href.casefold()
103
+ if lowered.startswith("javascript:"):
104
+ del link.attrs["href"]
105
+ continue
106
+ if lowered.startswith(("http://", "https://", "mailto:", "tel:", "data:")):
107
+ continue
108
+
109
+ special = _CHM_SCHEME_PATH.match(href)
110
+ if special:
111
+ href = special.group(1)
112
+ parts = urlsplit(href)
113
+ if not parts.path:
114
+ continue
115
+ candidate = normalize_member_path(
116
+ posixpath.join(current_dir, unquote(parts.path).replace("\\", "/"))
117
+ )
118
+ actual = member_lookup.get(candidate.casefold())
119
+ if actual and actual.casefold() in anchors:
120
+ link["href"] = f"#{anchors[actual.casefold()]}"
121
+
122
+
123
+ def _demote_headings(soup: BeautifulSoup) -> None:
124
+ for level in range(6, 0, -1):
125
+ for heading in soup.find_all(f"h{level}"):
126
+ heading.name = f"h{min(level + 2, 6)}"
127
+
128
+
129
+ def _best_title(soup: BeautifulSoup, fallback: str) -> str:
130
+ for selector in ("title", "h1", "h2"):
131
+ node = soup.find(selector)
132
+ if node:
133
+ value = " ".join(node.get_text(" ", strip=True).split())
134
+ if value:
135
+ return value
136
+ return fallback.strip() or "Untitled topic"
137
+
138
+
139
+ def _escape_link_text(value: str) -> str:
140
+ return value.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")
@@ -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
+ [![CI](https://github.com/zyyyz-a/markitdown-chm/actions/workflows/ci.yml/badge.svg)](https://github.com/zyyyz-a/markitdown-chm/actions/workflows/ci.yml)
40
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
41
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](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,14 @@
1
+ markitdown_chm/__init__.py,sha256=6d9BldnmZOluqXlqFLGIXeSGS3x-ji0VzLy4c-f_jic,696
2
+ markitdown_chm/cli.py,sha256=Fm5DY7xSPgcC86bhMeqh0CWLLDcEW4GT8Nvm5nGXGXc,2181
3
+ markitdown_chm/converter.py,sha256=EB9W2fEzU6Zr2j5HE8HxtUu_ov4rNikTbVhKv8SgyTo,8269
4
+ markitdown_chm/errors.py,sha256=CswKg8IYQI0xM5m4kIbInWhryenA_CyjsSZxl3nL4A4,277
5
+ markitdown_chm/limits.py,sha256=Xb-pw-vdnNH5OfPmC0OAg37tCflATY6bS3iKLlwPcS4,706
6
+ markitdown_chm/model.py,sha256=jCSb4nN7xKpwGCYb4aeMBvNqSwTpYAPeJooywmnoVds,500
7
+ markitdown_chm/parsing.py,sha256=LeJ3hvlGP8-ww3trzmX1VFRPWdFL4h5DYIQVdZzlZXE,5878
8
+ markitdown_chm/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
9
+ markitdown_chm/rendering.py,sha256=uHq91logetgcBT71jLpALMQyjqKXFwlKo0YEoBbnXHk,4341
10
+ markitdown_chm-0.1.0.dist-info/METADATA,sha256=mEcPQJL2Z5s9RdwBMfFA6PPT8aZldm3-B-cyhdyii_A,4821
11
+ markitdown_chm-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
12
+ markitdown_chm-0.1.0.dist-info/entry_points.txt,sha256=Fe6ZdDuAvDYfW3w-zizNY6Z0Bfqb0_4bkyTQ-3n6R_M,101
13
+ markitdown_chm-0.1.0.dist-info/licenses/LICENSE,sha256=Uk8sBuVtfIRPNy3jQ4TN0E7g3IcohIxCINk33cI4kEM,1065
14
+ markitdown_chm-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,5 @@
1
+ [console_scripts]
2
+ markitdown-chm = markitdown_chm.cli:main
3
+
4
+ [markitdown.plugin]
5
+ chm = markitdown_chm
@@ -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
+