Clean Documentation Template

This repo shows how Alex Krause (@alex0ptr) and Alexander Eimer (@aeimer) think how AsciiDoc, Antora and vale can be used to document your software and product better.

You can find the rendered Antora docs here

Structure

This repo has two main parts, the first can be found under templates and provide standalone files which can be used within the next part.

The second part shows how to set up a working Antora and all the by us suggested tooling. Almost any other files not under the templates directory belongs to this part. The templates provided are our suggestion to use within the documentation structure.

Content

From a technical perspective the following components are used.

Antora

TODO

Antora Lunr

TODO

Antora Collector

TODO

Antora Assembler

TODO

Antora Kroki

TODO

Vale

TODO

Pre-Commit

TODO

Differences to the real world

As this is a template which is contained within one repo, there are some differences to a real world setup.

• As suggested by Antora the playbook and the configuration files are stored in a separate repository. Having a "docs" repo with the playbook, config and some documentation content together works for some setups well, always look at your use-case. If in doubt start small and adapt if you grow.

• You probably want to have different repos as source defined in the antora-playbook.yml with branches or tags as references which state to use.

Using the Taskfile

Taskfile is a Makefile on steroids. You need to install Taskfile globally to use it.

# Install required dependencies via Brewfile
brew bundle

# Alternatively, install at least Taskfile (manually)
brew install go-task

# Show all tasks available
task

# Render documentation
task generate

# Render documentation and open in browser
task generate open
# or
task g o

# Open rendered documentation with http server
task serve

Useful links

• Diátaxis

• Antora

  • Antora collector
    A hook plugin to run custom code while generating the docs. It can be used to auto-generate nav.adoc files for dynamic content.

  • Antora assembler
    A plugin which has pure AsciiDoc as output and has all the Antora magic removed. It can be used to generate PDFs with the whole content.

• Vale

• AsciiDoctor Quick Reference

• One sentence per line rule

• Joels ADR

• blameless.com

• dastergon/postmortem-templates

• Alexander Schwartz

  • Talk about Antora
    ⇒ Demo repo to the talk

  • Another talk about Antora
    ⇒ IntelliJ AsciiDoc Plugin documentation

Support

This project is made possible with the support of