Re: Offer to contribute to documentation.
- Posted by petelomax 1 week ago
- 277 views
While asking about the over-tall index entry box in a chm file on Windows 11,
Would you like me to sketch out what a custom HTML index page (with a search box styled exactly how you like) might look like, so you don't need to rely on the built-in Index tab at all?
Sure, however one thing that absolutely must be possible is to open the chm on a specific index entry.
Got it - that requirement changes the design a bit. The built-in Index tab has the nice feature that you can launch
hh.exe -#klink mytopic chmfile.chm
or similar and it jumps right to that keyword. If you build a custom HTML-based index, you'll need to replicate that ability by controlling navigation inside your content. The good news is: you can.
How to build a custom index inside the CHM
Generate an index page (index.htm)
This is just another HTML topic inside your project, styled like the rest of your docs. Put your keywords in a searchable, clickable list. For example:
<!DOCTYPE html>
<html>
<head>
<title>Index</title>
<meta charset="utf-8">
<link rel="stylesheet" href="Combined.css">
<script src="Common.js"></script>
</head>
<body class="library">
<h1>Index</h1>
<input id="filter" type="text" placeholder="Type to filter...">
<ul id="index-list">
<li><a href="topics/introduction.htm">Introduction</a></li>
<li><a href="topics/example.htm">Example Program</a></li>
<li><a href="topics/functions.htm">Functions</a></li>
<!-- etc -->
</ul>
<script>
// simple live filter
document.getElementById("filter").addEventListener("input", function() {
const q = this.value.toLowerCase();
document.querySelectorAll("#index-list li").forEach(li => {
li.style.display = li.textContent.toLowerCase().includes(q) ? "" : "none";
});
});
</script>
</body>
</html>
This gives you a search-as-you-type box and a styled list, and you can make it look exactly how you like.
Make it openable by keyword
You can pass a query string in the URL when opening a CHM topic:
"hh.exe mk:@MSITStore:yourfile.chm::/index.htm?kw=example"
Inside index.htm, parse location.search and auto-focus that entry. For instance:
window.addEventListener("DOMContentLoaded", () => {
const params = new URLSearchParams(location.search);
const kw = params.get("kw");
if (kw) {
const match = [...document.querySelectorAll("#index-list a")]
.find(a => a.textContent.toLowerCase() === kw.toLowerCase());
if (match) {
match.scrollIntoView();
match.focus();
}
}
});
That way you can launch the CHM on index.htm?kw=Example%20Program and the right entry is highlighted.
Optionally integrate with TOC or search
You can link the custom index into your navigation tree, or even make it the default "home page" tab. Many people keep both: the old index for legacy hh.exe -#klink support, and the new one for a more polished experience.
Trade-offs
You won't be able to use hh.exe -#klink with the new HTML index (that only works with the built-in Index tab). Instead, you'd standardize on opening /index.htm?kw=....
You control all styling - no more tall, ugly textbox.
Works consistently across Windows 10/11 and in alternative CHM viewers.
Would you like me to show you how to keep the old Index tab for backward compatibility, but also add this new HTML index page as an alternative, so you can phase users over gradually?
I wasn't aware of any of that, and I haven't tried it. It sounds perfectly reasonable for me to build that index.htm automatically from the stuff I already have, and one thing that immediately springs to mind is that with the builtin index, typing "xpm" simply jumps to the first thing in the index that starts with that, whereas that index.htm will show me (say) "Greyscale_XPM" as well.
I was going to type "yes please", and then ask about a similar search page. Performance is not an issue, I've got 1200 files totalling less than 20MB so even a character-by-character fingertip approach seems unlikely to exceed a whole half-second, the only possible concern would be it making filter entry sluggish. The builtin search is whole-word-only, so "grey" it won't find greyscale, nor the latter greyscale_xpm, unless that word happens to occur in its description. But I thought I'd give you the opportunity to do that first, if you still want?
PS: If you start a new ChatGPT session with that first sentence edited to replace "Would you like me to" with say "For a chm file, can you", ...
