Aggregate AsciiDoc from multiple repositories
AsciiDoc is my favorite text processing tool, I basically use it everywhere - well except in in this blog. It has lots of advantages over Markdown, but don’t let us delve into preferences that aren’t the thing I want to write about.
So back to writing documentation in AsciiDoc: Sometimes there is a requirement to include docs from multiple sources, but it is kind of difficult to aggregate this properly and to combine it to a single document.
There is surely a way to use something like git modules, but there are also not many faster ways to annoy me.
So time to check out Antora:
The multi-repository documentation site generator for tech writers who <3 writing in AsciiDoc. https://antora.org
According to this, this looks really interesting and promising. And after a few hours down the road I managed to actually generate docs and found a few gotchas.
So here is the general idea about Antora: On the sourcing side, you just have a plain yaml file - the playbook - which contains every source you want to aggregate. Each of the sources must be a working git repository with at least one actual commit.
site: title: Showcase for antora url: https://hg.unexist.dev/showcase-antora start_page: showcase-architecture-documentation::index.adoc # <1> content: sources: - url: https://github.com/unexist/showcase-architecture-documentation.git start_path: docs # <2> ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable snapshot
<1>: This sets the default start page for the whole document and can be from any included source.
<2>: Here the start path in the repository is set; this defines where the antora.yml is.
Inside of each repository there has to be another config file - the component descriptor - which is read after a checkout of the repository and basically provides Antora with a bit of meta informationen
name: showcase-architecture-documentation title: Showcase for architecture documentation version: 0.1.0 start_page: ROOT:index.adoc # <1>
<1>: This sets the start page of the module.
That is all that is required from the config part - let us talk about the structure. First of all, there is no reliable way to use a custom layout and the structure from Antora’s authors has to be used.
No I am not kidding, see here: https://gitlab.com/antora/antora/-/issues/28
I’ve tested this for quite some time, here are my learnings:
- There is no way around this fixed structure it; although there is a theoretically way to use something like this.
- I read symlinks might be a possibility - no they are not; don’t waste time here.
- Themes act weird and it is probably better to just keep the default one.
My showcase can be found here: