Creating an index? (a proper index)

I’m currently writing a Python programming course in an CMS that my university uses. Based on previous experiences with this CMS I’m writing all material in markdown, convert it to HTML and paste it in systems editor. In short I have all material in Markdown format and I’ve been playing with the idea of making a web site of the whole thing. While thinking about this I thought it would be nice to have a real index, I’m talking about a “book version index” with words and links back the the places/pages where this word occurs.

Can this be done using Hugo? How?

Hugo supports HTML markup. So if you want to use Hugo you would need to convert your markdown to HTML with a script and then you could use the generated markup with Front Matter within Hugo.

Hmm, a super rough version of what you want is to use a taxonomy, but, that’s a blunt tool. You might be able to get a list of tokens in the index somehow, from one of the search engine apps, like lunr, solr, elasticlunr, algolia etc., to at least point a term/token to a page.

However, if you wanted positional jumping (i.e. click the index link and it not only goes to the page, but to the position on the page) you’d need some id assigned on a <span> around the word on the page. That sounds like something that would have to be built and injected, after Hugo generates the HTML.

What does your vision look like?

I’ve played every edition of D&D, so I’ve spent literal days scanning indices. It is silly for a website, of course, but fancy, I get it! So I was thinking about it, and I don’t know what it looks like.

You don’t want to link to a direct word, because that isn’t how an index works. It takes you to the sequential location. For the web, we’d link something to a webpage, or more usefully, a heading. Okay, that kinda makes sense.

But what is the thing we are linking? Is it a word? Does each “heading” in the index contain exactly one “locator”, the heading itself? But you said “places/pages”, so how do we denote those links? Not by numbers, but if we link to titles or headings, our index starts to look kinda weird, and it is hard to scan for words easily.

You can script it to look and interact anyway you want, of course. But I was curious of what you saw. :slight_smile:

I don’t know if it’s silly for web site, I think it all depends on what the intended use of the web site is. I was thinking about an index similar to what you can find in a standard text book: a list of words & terms with a reference to where they can be found.

A web site can contain links to other sections which is great, it also allows for search which is also great. My problem is that I sometimes want to see where a specific word/term is used, in a book I can usually go to the index to see where it’s defined and also other places where it’s used in some way. In theory I would be able this using search but my experience is that search gives many non-relevant hits, non-relevant is the sense “Yes, this word/term is used here but it doesn’t provide any useful information”.

The idea I was toying with (I haven’t committed to actually do this … at the moment I have no time to do this) was for me to be able to mark some piece of text as the definition and then some other instances as “useful”. An example to make it clearer: I’m writing this newbie programming tutorial and explain what recursion is and while I’m writing this I’m able to mark this as “the definition”. In some other place I discuss binary search and write “it can implemented either iteratively or using recursion as these two example show”, I would mark this to be included in the index for recursion since it contains some useful example of how to use recursion. In a third place there might be some text that says “instead of the usual recursive solution this is based on iteration”, this is not marked to be included in the index since it doesn’t give any useful information about recursion. In a fourth place there might be some code example which uses recursion but the word is not mentioned, this is marked to be included in the index under the word “recursion”

So someone who needs to look up information about recursion can search for “recursion”, this would bring up all places where the word is mentioned including the less informative page but not the useful example. With an index I would see where I could find the definition and other useful pages (perhaps also a traditional “see also” suggestion).

I think this would be quite useful for a web site like this, I can find material by using a table of content (a traditional web index), search (always good to have) and also an index that links to useful places on the web site.

What does it look like? That determines how it is created.

Recursion, 1 2 3

or

Recursion

or

Recursion: Recursion in Recurse, Review of Recursion

How is your index rendered in HTML? What are the reference links?

What you have described sounds like two separate features: an index and a glossary.

The Index would require changes in Hugo since Hugo doesn’t offer any site-wide writable data structure from within shortcodes/templates. You essentially need to update a taxonomy (or a similar data structure) from within a shortcode. For example:

Blah blah {{< index >}}recursion{{< /index >}} blah blah.

Example shortcode:

{{ $ref := index.AddTerm . .Inner }}
<a href="#{{ $ref }}">{{ .Inner }}</span>

The Index feature is an interesting one. We’d have to deal with things like different languages and index variants (multiple indexes in once site). @bep, what are your thoughts?

Your Glossary feature would need similar changes, but I’d be more inclined to maintain a separate, explicit page for a glossary and simply link to that page (something Hugo already supports). I’m not sure it’s worth the effort to add an esoteric glossary feature, but I suppose you could generalize the Index feature to cover this additional use case.

I think it is a very hard problem to solve well.

1 Like

As I mentioned above this is just an idea I got while writing stuff for this CMS (it’s based on Sakai) which had no similarity what so ever to any static generator, so there is nothing in existence that I can point to.

As for how it could look like: I could imagine both alternative 1 och 3. The first would be compact but it would lack any contextual information, the last would have the contextual information but could become very very large.

Perhaps something like:

Recursion: How recursion works, Binary Search, QuickSort, Printing a tree in reverse order

I probably described my idea badly, but as I see it would be only one feature: the index. The definition part wouldn’t be a glossary item but rather a part (page/section) of the whole tutorial which is supposed to explain something in detail.

Please do not spend any time on this, it was just an idea that I got while working with this CMS (which doesn’t have this feature either) and I just wanted to know if this was something that Hugo supported.

I’m quite sure that there are other more worthwhile stuff to do.