textindex: generate index (of concepts) from Markdown files

ctietze

Another cool tool by Matt Gemmell:

https://mattgemmell.scot/textindex/

It introduces curly braces in some places to mark words or phrases for index generation, like so, piggy-backing on what looks a bit like footnotes (which would use square brackets) and links:

Most mechanical keyboard firmware{^} supports the use of [key combinations]{^}.

This would put "firmware" and "key combinations" into the index. Scroll down on the linked page for an example index that was generated for that documentation page itself.

I love the simplicity of this. I don't love extending Markdown Working on The Archive and wrestling with Markdown flavors has scarred me. Since this is opt-in and purely additive and runs as a pre-processor of sorts, it doesn't prevent you from using whichever tool you like to write, though. Most or all will just not highlight the curly braces for you.

Andy

Gemmell's website has been down for at least an hour, so I haven't seen it yet and don't know if Gemmell discussed prior solutions to this problem, but upon reading @ctietze's post I was sure somebody must have created a solution before, and indeed there is, for example, a GitHub issue for Pandoc from 5 years ago that talks about using a Pandoc filter to generate a concept index like this.

Pandoc filters are a common solution to this kind of problem; pandoc-crossref (a Pandoc filter for numbering figures, equations, tables and cross-references to them) is an example of one that I use.

Andy

Now that Gemmell's website is back up, I can see the page linked above about TextIndex, and the feature set is more complex than I expected. Impressive!

mattgemmell

Apologies for the site downtime; an Akamai issue which was resolved within a few hours.

Thanks for taking a look at TextIndex. My intent was to make it as comprehensive as simplicity would allow, with a focus on the end product of usable, attractive indexes. I've been using it myself to index a variety of documents as a way to test the syntax and functionality, and I think it's turned out well. I hope it'll be useful to others too.

I consider it to (provisionally) be functionally complete as of today, after I fixed a few bugs and added some features:

• Inbound cross-references
• Run-in style option for deepest level (>2)
• Letter-headings option for indexes
• Wildcards can now also be used in sort-keys and cross-refs

The documentation and the repository have been updated.