How to Use WEB2CHM for Offline Help FilesCreating offline help files is essential for software documentation, training materials, and any situation where users need access to information without an internet connection. WEB2CHM is a tool that converts HTML pages (single files or entire websites) into a single compiled CHM (Compiled HTML Help) file. This guide walks you through preparing your content, using WEB2CHM effectively, customizing the output, troubleshooting common issues, and best practices for distribution and maintenance.
What is WEB2CHM?
WEB2CHM converts HTML content into a CHM file, a Windows help format that bundles HTML pages, images, stylesheets, and a compiled index into a single file with built-in navigation. CHM files remain useful for Windows applications, internal documentation, and legacy systems where a compact, offline help format is required.
When to use WEB2CHM
- You have documentation already written in HTML and want a single-file, offline help package.
- You need a searchable, indexed help file for Windows-based applications.
- You want to package tutorials, API docs, or manuals for distribution with a desktop installers or internal networks.
- You need TOC (table of contents), index, and context-sensitive help features in one file.
Preparing your HTML content
Good input makes a better CHM. Follow these preparation steps:
-
File structure
- Organize HTML files in a clear folder hierarchy (e.g., /topics, /images, /css).
- Use relative links between pages (avoid absolute URLs that point to the web).
-
Clean HTML
- Ensure pages are valid HTML (fix broken tags).
- Remove or adapt scripts that require server-side execution (PHP, server-side includes). CHM displays client-side JavaScript but complex dynamic features may not behave as intended.
-
Resources
- Place images, CSS, and fonts in subfolders and reference them with relative paths.
- Avoid external CDN references for critical resources; bundle assets locally.
-
Main entry page
- Create a clear index.html or default.html that acts as the help file’s home page.
- Add a short introductory section and navigation links to major topics.
-
Metadata for search and indexing
- Use descriptive page titles and headings (H1/H2) to improve internal navigation and searchability within the CHM.
Installing and launching WEB2CHM
There are several tools named similarly; this guide assumes a typical WEB2CHM utility that compiles local HTML to CHM. Installation steps:
- Download WEB2CHM from the official site or trusted repository.
- Run the installer or use a portable executable, depending on the package.
- Ensure the Windows HTML Help Workshop (hhc.exe) is available — many WEB2CHM utilities call Microsoft’s HTML Help compiler. If not included, download and install Microsoft HTML Help Workshop first.
Launch WEB2CHM after installation. You’ll usually see a GUI with fields to specify the source folder, main file, output filename, and options for TOC and index generation.
Basic conversion workflow
-
Select source folder
- Point WEB2CHM to the root folder containing your HTML files and assets.
-
Choose the entry page
- Specify the main page (index.html) that will open when the CHM is launched.
-
Configure output
- Specify the CHM file name and output location.
-
Table of Contents (TOC) and index
- Some versions auto-generate TOC from folder structure and page headings.
- For precise control, you can build a TOC file (.hhc) and index file (.hhk). WEB2CHM may provide editors to create and reorder topics.
-
Compile
- Click “Compile” or “Build.” The tool typically invokes hhc.exe to produce the final .chm file.
- Monitor logs for warnings or errors (missing files, bad links).
Customizing the CHM
-
Table of Contents (.hhc)
- Create a hierarchical TOC that mirrors your documentation structure.
- Use meaningful labels for each node; avoid overly long names.
-
Index (.hhk)
- Add keywords and link them to the appropriate pages for quick lookup.
- Consider synonyms and common misspellings.
-
Search settings
- CHM supports full-text search. Ensure pages include text (not just images) and avoid heavy use of dynamically injected content.
-
Branding and appearance
- Customize the start page with your logo, colors, and a welcome message.
- Include a footer with version, date, and contact/support information.
-
Context-sensitive help
- If integrating with an application, set up context IDs for specific topics and configure your application to call the CHM help API with those IDs.
Advanced tips
- Pre-generate TOC and index: For large docs, manually preparing .hhc and .hhk files gives better structure than auto-generation.
- Use frames or a left-pane TOC layout if your users expect persistent navigation while reading topics.
- Optimize images (compression, appropriate formats) to reduce CHM size.
- Minify CSS and inline small scripts to reduce file count and complexity.
- Disable or adapt scripts that rely on internet resources or asynchronous loading.
- Use descriptive title tags and meta descriptions to improve CHM search relevance.
Troubleshooting common issues
- Broken links after compilation:
- Check for absolute URLs or incorrect relative paths. Rebuild with corrected links.
- Missing images or styles:
- Ensure referenced files are included in the source folder and paths are relative.
- JavaScript not working:
- Secure contexts, cross-origin calls, or server-side dependencies won’t work. Replace with static alternatives or simple client-side code.
- Compilation errors:
- Inspect the hhc.exe log for missing files or syntax issues in .hhc/.hhk files.
- CHM blocked by Windows (when downloaded):
- Windows may block CHM files downloaded from the web. Right-click the file -> Properties -> Unblock, or distribute via installer that handles this.
Distributing and maintaining CHM files
- Versioning: Include a version number and build date on the start page and file name (e.g., MyDocs_v1.2.chm).
- Update process: Rebuild CHM whenever content changes; keep source HTML in a version control system for tracking.
- Distribution: Bundle CHM with installers, provide via internal servers, or give as a downloadable attachment. Note CHM security restrictions when distributed over the internet.
- Accessibility: CHM has limitations for modern accessibility features. Provide alternative formats (PDF, web, or accessible HTML) for users who need screen readers or non-Windows platforms.
Alternatives and when not to use CHM
- Use CHM when targeting Windows-only users who need a compact, searchable offline help file.
- Consider alternatives if:
- You need cross-platform offline help (use PDF or packaged HTML apps like Electron).
- You require modern web features or complex interactivity (maintain a web version).
- Accessibility and compatibility with non-Windows systems are priorities.
Comparison (high level):
| Feature | CHM (WEB2CHM) | Packaged HTML (Electron) | |
|---|---|---|---|
| Single-file distribution | Yes | Yes | No (but can be packaged) |
| Searchable full-text | Yes | Limited (text search) | Yes |
| Windows-only | Mostly | Cross-platform | Cross-platform |
| Interactive content | Limited | Very limited | Full web capabilities |
| Size and overhead | Small | Small to medium | Large |
Quick checklist before compiling
- [ ] HTML files validated and linked with relative paths
- [ ] All images/CSS/fonts included locally
- [ ] Main entry page set (index.html)
- [ ] TOC (.hhc) and index (.hhk) prepared or auto-generation acceptable
- [ ] Microsoft HTML Help Workshop installed (if required)
- [ ] Test CHM locally and on a clean Windows machine
Example: Minimal .hhc TOC snippet
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <UL> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Getting Started"> <param name="Local" value="topics/getting_started.html"> </OBJECT> <LI> <OBJECT type="text/sitemap"> <param name="Name" value="Configuration"> <param name="Local" value="topics/configuration.html"> </OBJECT> </UL> </HTML> Final notes
WEB2CHM is a practical solution when you need a tidy, Windows-friendly help file from existing HTML documentation. Proper preparation of source files, thoughtful TOC and index design, and attention to compatibility will yield a professional, user-friendly CHM.
Leave a Reply