Special block with tags, automatically generate lists by tag

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Special block with tags, automatically generate lists by tag

Guillem Marpons
Hi all,

I'd like some advice on what option to try first in the following use case.

I'm writing a doc that contains "guidelines". There are 3 or 4 different kinds of guidelines. A Guideline has:

* A title
* Contents
* An automatic Id generated with some Asciidoctor counters
* A list of tags
* A list of related guidelines

I'm currently putting every guideline in a sidebar, and using roles to declare different kinds of guidelines.

I'd also like to define the list of tags and list of related guidelines as declaratively as possible (ideally in the same attribute list of the sidebar block), and then be able to:

1. When showing the sidebar for a guideline, add tags and related guidelines info, can be via HTML data-* attributes + JS.
2. At some point of the document, insert a table with all the guidelines containing a specific tag. Generate those tables as automatically as possible.

My main concern is long run maintainability of the solution. It should be possible to easily add/remove/modify guidelines with the smallest possible amount of ad-hoc JS/Ruby code (but JS code that is front-end-specific is less problematic).

Main output is HTML, using Antora. PDF would be a secondary goal, but I know it's difficult to have a solution that works for both.

Some options I see:

* Custom templates for (1), and then use sed or AWK to generate a CSV that then I can include as a table for (2). The CSV files could be commited to the source repo as normal inputs, not necessarily generated on-the-fly. Can this work with Antora at all?
* Have two block processor extensions for a new type of node that replaces sidebars. One is used offline to generate the table files, the other is run by Antora to render a guideline, including tags and refs to related guidelines.
* Custom macro + block macro processor extension. But I'd like to have complete freedom for formatting guideline's contents.