Generate xref attributes for all topics in manifest

[briandominick]

Cross-references are a big problem in most static-based websites, and this is not resolved by adding AsciiDoc to the mix, even though AsciIDoc has xrefs built in. At the time of conversion, each page is treated like a distinct document, and Asciidoctor does not know what other documents are, let alone where they are.

This is the reason to use a manifest that generates menus and also records some metadata for each topic, so there is a central dataset that understands the information architecture and knows all the paths.

To render hyperlinked cross-references (xrefs)in this theme (or any jekyll-asciidoc-driven site), we use syntax like <</path/to/topic#,Topic Title or Other Text Here>>. This means we must know the exact URL of the resource and its title, and if those change, we'll have to search-and-replace to catch xrefs.

Alternatively, we could pre-generate a big set of xrefs and store them and make them available as AsciIDoc attributes (variables). For example, <<{xref_topic-slug-here}>> could render an xref just like the previous, conventional syntax. Or use <<{xref_topic-slug-here_notitle},some arbitrary text>> if you don't want to render the title of the referenced toipic.

That is the simple part. The hard part is loading them for each document build. Every document build ingests AsciiDoc attributes from site.asciidoctor.attributes, but those are sourced as static YAML files that won't exist at the top of the build when they're required.

Alternatively, we can generate an attributes.adoc file (using a Jekyll include), and then we can embed that at the top of each topic as an AsciiDoc include (I think?), but in this case we would need a reference this include in any file that uses the xref variables. I don't think there's a way to use layouts or any other global feature to ingest the attributes on a per-topic basis.

The only other option I can think of at this time is to create a plugin that preprocesses the manifest into a list of AsciiDoc attributes and ingests it. This might be optimal, and then it would apply to any theme that wanted to use it, right out of the box.

[briandominick]

I ran some experiments on methods for doing this, and

To my mind, the only real options for enabling xref attributes are:

1. Create a Jekyll plugin that piggy-backs on jekyll-asciidoc to generate and ingest attributes at runtime, or
2. Perform a prebuild with a tool like LiquiDoc and then ingest everything at runtime

I don't have a great argument for preferring Option 2, and I kind of think having this work out of the box with Jekyll is ideal, but I'm not going to prioritize it for 1.0 unless I get a lot of demand for it. I will document and provide a framework for doing it with LiquiDoc, at the very least, because this functionality is extremely advantageous.

Some other things such a plugin could do: 1a. Enable TOCs for each build based frontmatter, no manifest needed. 1b. Add subheadings to xrefs

LiquiDoc does not at this time do anything with Jekyll frontmatter, so we have been storing topic metadata in central (YAML) files and transforming them into new data objects for Jekyll, etc or attributes lists for ingesting into Asciidoctor conversions. It helps keep the toolchain SSG-agnostic (i.e., it will work w/ Jekyll competitors).

It does seem to me that the ability to distribute topic metadata to frontmatter in the topic files themselves would be highly preferable for some settings, so it would be great to enable it as a Jekyll plugin that just makes tons of contextual data available throughout the build. I don't want this to hold back 0.3.0 or even 1.0GA, so I'm going to remove this from the Project till but keep it open.