Building Documentation At Scale
with Antora and Asciidoc
by Hakim CassimallyTODO: explain rationale for this book and my credentials for writing it:
-
running a big docs site is a bigger task than people who’ve never done it might imagine.
-
Docs-as-Code in general has many advantages which compound as the documentation ask gets bigger and more complex.
-
The Antora project exemplifies many of the features required.
-
How the book is organised
Table of Contents
-
-
Simple sites
-
Colocation in monorepo vs multiple repos
-
Branches
-
start_paths
-
for multiple content sources
-
or shared dev repos
-
-
many-to-many nature
-
visualising your playbook relationships
-
-
Generating the playbook with diffs
-
-
by components
-
by module
-
by version
-
paragraphs / bulleted lists etc.
-
tab sets
-
How do these different categorisation options affect how we use version control to keep these differences in sync?
-
IA for all these products you now have.
-
contextual navigation
-
-
terms. stylisation. indexing. linking.
-
page-aliases again?
-
overriding the url component
-
-
Every page is page one
-
When was a page changed?
-
Configuring attributes different levels of content:
-
global (antora-playbook attributes)
-
component (antora.yml attributes)
-
module (OH NO! - do it with an extension?)
-
page (frontmatter)
-
-
Banners
-
Reorganising content
-
page-aliases
-
-
Images, alt text, captions, descriptions
-
AI-ready docs
-
llms.txt
-
markdown summaries
-
-
Code examples
-
syntax highlighting
-
includes by line number / tag
-
use Compy
-
custom include processor
-
-
callouts
-
-
Generating content
-
attributes
-
templated content
-
redocly etc.
-
kroki
-
antora-collector
-
manual script
-
working with other teams
-
-
Previews
-
building when things change (event bus / polling / state)
-
-
The UI
-
why it matters
-
suggestion: keep in same repo
-
-
Search
-
Niche uses of Antora
-
blog
-
slides
-
CV
-