Aggregate AsciiDoc from multiple repositories

Christoph Kappel · · , , , , · Reading time 3 minutes
In this article

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.

Time to check out Antora.

Antora

The multi-repository documentation site generator for tech writers who <3 writing in AsciiDoc.
— https://antora.org

According to this, this looks fascinating 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.

Conclusion

When you can really stick to the modules structure, Antora is a really nice tool and probably easier to use than the Java tooling for AsciiDoc.

My showcase can be found here:

https://github.com/unexist/showcase-antora