Add tooling to generate "jump" lists

[dedemorton]

It's fairly common in modular documentation to use jump lists to point to the topics that are nested under a larger container topic. Right now, we hand code those lists, and they get out of sync with the docs fairly quickly. We need some kind of macro or tooling that lets us generate jump lists automatically. Here's an example of a jump list:

https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html

(I'm using this topic as an example, but for this particular topic, we do actually generate the content. The logic is very specific to modules and where they live in the repo, so it's not really reusable.)

Originally, we didn't have jump lists in topics like this, and we heard from users who thought the content was missing or not loading correctly. You'd think people would look at the TOC, but in topics like this, the relevant part of the TOC is not even visible, and users don't always realize they need to scroll down to see the full TOC.

[debadair]

@gchaps proposed a different solution that eliminates these "nav" pages in favor of having "categories" in the TOC structure that provide signposts without being linked pages that show up in search results and force people to click through. A frequent complaint is that you have to click through too many pages to get to meaningful content, and proliferating this sort of jump-list page probably isn't necessary if we have a better navigation infrastructure.

That said, there might still cases where it makes sense to embed a link list of subpages, and being able to generate/maintain the links automatically would be vastly better than creating them manually.

[dedemorton]

@debadair I'm OK with removing the jump lists when we have a better nav design. We added them because some users were confused when they visited a short topic. They couldn't see the sub-topics that were available if the topic was towards the bottom of the TOC.

[bmorelli25]

I'm starting to notice this problem in the APM documentation as well. I agree that they can be removed with a better nav design, but for now, they really are needed on topics where the TOC is hidden down the page. Would be great to have some sort of tooling that keeps these in sync.

[nrichers]

The Cloud docs could also benefit from a solution that isn't maintained manually. We've added short overview topics for major sections in our docs, but they tend to go stale and require periodic fixing as people add new content. In DITA, you can generate this info from the contents of the tag, but there's no Asciidoc analogue that I have found.

[dedemorton]

Closing this because it's been open for awhile. I doubt we'll solve it in the current system, and it will no longer be an issue in the new system.