Skip to content
Back to search

chm-converter

chm to markdown and vectorDB

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dtducas--chm-converter/badge.svg)](/listings/dtducas--chm-converter)

HTML

<a href="/listings/dtducas--chm-converter"><img src="/api/listings/dtducas--chm-converter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/DTDucas/chm-converter.git
cd chm-converter
pip install -r requirements.txt

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 164 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # CHM to Markdown Converter
  2. A Python utility for converting Compiled HTML Help (`.chm`) files into clean Markdown, with built-in support for multiple document types through a profile system.
  3. Originally built for Autodesk Revit API documentation; the generic profile works with any CHM file.
  4. ## Features
  5. - **Profile-based conversion** — `generic` profile for any CHM, `revit` profile for Autodesk Revit API docs
  6. - **Auto encoding detection** — handles UTF-8, GB18030, GBK, GB2312, and more via `chardet`
  7. - **Cross-platform 7-Zip detection** — finds `7z`/`7za`/`7zz` on PATH (Windows, Linux, macOS)
  8. - **Flexible CHM structure support** — handles `html/` subdirectory, flat, and deeply nested layouts (e.g. DirectX SDK)
  9. - **`--preserve-structure`** — optionally mirrors the CHM's internal folder hierarchy in the output instead of flattening everything into `data/`
  10. - **Code block preservation** — detects language from class names and named divs; supports C#, VB, C++, F#, Python, Java, JS/TS, Bash, SQL, XML, JSON
  11. - **Table normalization** — cleans and re-formats Markdown tables
  12. - **Index generation** — produces `file_index.json`, `id_lookup.json`, and `index.md` for search and AI integration
  13. - **Async + batched processing** — bounded concurrency and periodic GC prevent memory overflow on large CHM files (6 000+ pages)
  14. ## Project Structure
  15. ```
  16. chm_converter/ # Core package
  17. ├── config.py # ConversionConfig dataclass + built-in profiles
  18. ├── encoding.py # Encoding detection (chardet + CJK fallbacks)
  19. ├── extractor.py # CHM extraction via 7-Zip; HTML folder detection
  20. ├── html_processor.py # HTML cleaning, link rewriting, code block extraction
  21. ├── md_converter.py # HTML → Markdown conversion + post-processing
  22. ├── indexer.py # File dictionary building + index file generation
  23. └── pipeline.py # High-level async pipeline (process_chm_file, process_all_chm_files)
  24. chm_to_markdown.py # CLI entry point
  25. resources/ # Place CHM files here
  26. output/ # Generated Markdown (created automatically)
  27. ```
  28. ### Output layout
  29. ```
  30. output/
  31. └── <name>/
  32. ├── core/
  33. │ ├── file_index.json # id → {title, filename, version}
  34. │ ├── id_lookup.json # lowercase id → {title, filename, keywords, version}
  35. │ └── index.md # alphabetical navigation page
  36. └── data/
  37. ├── Topic1.md
  38. ├── Topic2.md
  39. └── ...
  40. ```
  41. ## Requirements
  42. - Python 3.10+
  43. - [7-Zip](https://www.7-zip.org/) — `7z` must be reachable via the default install path or `PATH`
  44. - Windows: installs to `C:\Program Files\7-Zip\7z.exe` by default, or add to `PATH`
  45. - Linux: `sudo apt install p7zip-full`
  46. - macOS: `brew install p7zip`
  47. ## Installation
  48. ```bash
  49. git clone https://github.com/DTDucas/chm-converter.git
  50. cd chm-converter
  51. pip install -r requirements.txt
  52. ```
  53. ## Usage
  54. Place `.chm` files in the `resources/` folder, then run:
  55. ```bash
  56. # Interactive menu (lists available CHM files)
  57. python chm_to_markdown.py
  58. # Convert a single file
  59. python chm_to_markdown.py --single resources/docs.chm
  60. # Convert all CHM files in resources/
  61. python chm_to_markdown.py --all
  62. # Use the Revit API profile (strips Revit help-viewer boilerplate)
  63. python chm_to_markdown.py --all --profile revit
  64. # Preserve the original folder hierarchy inside data/ (e.g. for DirectX SDK)
  65. python chm_to_markdown.py --single resources/directx_sdk.chm --preserve-structure
  66. # Keep extracted HTML for debugging
  67. python chm_to_markdown.py --single resources/docs.chm --keep-html
  68. # Tune performance
  69. python chm_to_markdown.py --all --workers 4 --batch-size 25 --semaphore 10
  70. ```
  71. ### CLI arguments
  72. | Argument | Short | Default | Description |
  73. | ---------------------- | ----- | --------- | --------------------------------------------------------------- |
  74. | `--single FILE` | `-s` | — | Convert a single CHM file |
  75. | `--all` | `-a` | — | Convert all CHM files in `resources/` |
  76. | `--profile` | `-p` | `generic` | Conversion profile: `generic` or `revit` |
  77. | `--keep-html` | `-k` | off | Retain extracted HTML after conversion |
  78. | `--workers N` | `-w` | `8` | Thread-pool size for CPU-bound conversion |
  79. | `--batch-size N` | `-b` | `50` | Files processed per async batch |
  80. | `--semaphore N` | — | `20` | Max concurrent I/O operations |
  81. | `--preserve-structure` | — | off | Mirror CHM folder hierarchy in `data/`; preserve relative links |
  82. ## Profiles
  83. | Profile | Description |
  84. | --------- | ---------------------------------------------------------------------------------------------------------------------- |
  85. | `generic` | Minimal cleanup — works with any CHM file |
  86. | `revit` | Strips Autodesk Revit help-viewer UI chrome (collapsible regions, feedback links, code-tab toolbars, boilerplate text) |
  87. Custom profiles can be created programmatically:
  88. ```python
  89. from chm_converter.config import ConversionConfig
  90. from chm_converter.pipeline import process_chm_file
  91. import asyncio
  92. cfg = ConversionConfig(
  93. classes_to_remove=["my-nav-bar", "site-footer"],
  94. ids_to_remove=["cookie-banner"],
  95. cleanup_patterns=[
  96. (r"Rate this article.*?---", "---"),
  97. ],
  98. )
  99. asyncio.run(process_chm_file("docs.chm", "extracted", "output", cfg=cfg))
  100. ```
  101. ## AI Integration
  102. The `core/` folder is designed for RAG and AI search pipelines:
  103. - `file_index.json` — maps every file ID to its title, filename, and version
  104. - `id_lookup.json` — lowercase-keyed with extracted keyword lists for full-text search
  105. - `index.md` — human-readable alphabetical index with anchor links
  106. ## Troubleshooting
  107. | Problem | Solution |
  108. | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
  109. | `7z not found` | Install 7-Zip and ensure it is on `PATH`; see Requirements above |
  110. | Empty output / `No HTML files found` | CHM uses a nested folder layout — add `--preserve-structure` to enable recursive traversal |
  111. | Revit 2025+ pages contain only a title, no body | Fixed in current version: `TopicContent` is no longer stripped from the Revit profile |
  112. | Garbled CJK text | The tool auto-detects encoding via `chardet`; try `--profile generic` if issues persist |
  113. | Memory errors on large CHM | Reduce `--workers` and `--batch-size` |
  114. | Permission errors | Run the terminal with administrator / sudo privileges |
  115. ## License
  116. MIT License
  117. ## Author
  118. **Duong Tran Quang (DTDucas)**
  119. baymax.contact@gmail.com
  120. [github.com/DTDucas](https://github.com/DTDucas)
  121. Author: [dtducas.com](https://dtducas.com)
  122. ### Contributors
  123. - **Jiangxumin** — Chinese encoding support, cross-platform 7-Zip detection, memory-safe batch processing ([PR #11](https://github.com/DTDucas/chm-converter/pull/11))

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.