Generating an index

[gvwilson]

I've added another extension to https://github.com/gvwilson/theme to generate an index, but I believe my approach has broken caching.

1. The i shortcode in lib/mccole/extensions/index.py translates index entries into links, and as a side effect, records all index keys and the files they appear in. So far, so good.
2. I want to define another shortcode to generate a list of all index entries for inclusion in an appendix. However, if the appendix page is not the last one to be generated, not all of the index entries will have been collectedl, and the index will be incomplete.
3. I therefore use an "exit" event handler to to read the generated HTML back in and insert the generated index.

This approach is ugly; it also seems to confuse the file cache. Is there a better approach?

[gvwilson]

Re-upping this: is there a way to ensure that a particular page is converted to HTML last, so that all indexing information will have been collected?

[dmulholl]

I'm not sure what's happening here, caching is always a mixed blessing I'm afraid.

If all else fails, you can call ivy.hashes.clear() to clear the cache. Unless the site is huge, it probably won't make a significant difference to the build time.

There's no robust way to determine the last page to be generated -- it depends on the alphabetical ordering of the filenames which is inherently brittle.

I suspect a better solution might involve calling ivy.nodes.root() yourself on the INIT hook:

root_node = ivy.nodes.root()

This will force Ivy to build the node tree. You can then traverse the nodes and do whatever manipulations you like before any of the build or output hooks fire.

[gvwilson]

Am I correct that the build step generates the HTML and saves it to disk? Or does build generate HTML in memory, which is written to disk later (e.g., in the exit stage)?

[dmulholl]

The build command generates the node tree and writes each node to disk as a HTML file. It covers the default use case.

You can generate the node tree independently of the build command -- e.g. that's what the tree command does. It generates the node tree, then prints it (or a representation of it) to stdout.

You could define your own say epub command that generates the node tree and then writes it to disk as an ebook.

[gvwilson]

What I've come up with is:

1. Walk the tree during the INIT phase.
2. Use a custom shortcode parser to extract information about index entries and store for later.
3. Use a new [% index %] shortcode to insert that information during the BUILD phase.

It means shortcode-parsing each file another time (making three in total: figures, tables, and index entries), which is a performance hit, but I can consolidate that.

[dmulholl]

Sounds good 👍 I'd never even considered that kind of use case for shortcodes.