Creating a documentation site for users with AsciiDoc and Antora

For developers it is normal to develop software in collaboration using their IDE and a version control system like Git. The same type of collaboration is possible when all documentation is versioned in a markup-format like AsciiDoc.

The tool Antora creates documentation websites from AsciiDoc sources stored in Git repositories. Users can browse the generated website and select the version matching the software they use. Navigation outlines, search and cross-references between pages allow users to find answers to their questions. Several open-source software projects like Camel, Debezium and Couchbase use this solution.

This talk presents the basics of an Antora setup and walks through all the steps from editing content in the IDE to updating the documentation site using continuous integration and delivery.

Transcript

1. Creating a documentation site for users with AsciiDoc and Antora Alexander Schwartz, Principal IT Consultant Jfokus Brown Bag Session, 2020-12-10
2. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 2 Creating a documentation site for users with AsciiDoc and Antora Empower your users with documentation 1. Using AsciiDoc and Antora 2. Setting up Antora 3. Summary 4.
3. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 3 Empower your users with documentation so they get their work done Motivation • Online, up-to-date, automated • Searchable and topic-based • Navigation and cross references • Grouped by version and component
4. 4 Creating a documentation site for users with AsciiDoc and Antora © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz Empower your users with documentation 1. Using AsciiDoc and Antora 2. Setting up Antora 3. Summary 4.
5. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 5 AsciiDoc is the language, Asciidoctor is one toolchain Asciidoctor https://asciidoctor.org/ AsciiDoc • friction-less writing using plain text • feature-rich syntax for technical documentation • 15 years alive and kicking • standardization started in 2020 at Eclipse Foundation Asciidoctor • toolchain to create HTML and PDF from AsciiDoc files • OpenSource implementation • runs on Java, Ruby and JavaScript runtimes • powers Antora’s AsciiDoc to HTML conversion AsciiDoc Eclipse Working Group
6. • stay focused and don’t switch apps • collaborate using version control • AsciiDoc plugin for IntelliJ provides Antora and AsciiDoc support © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 6 Writing in the IDE List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
7. 7 © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz Antora: Publishing tools and documentation structure • Structure documentation into components and modules • Collect content from multiple repositories and branches • Convert AsciiDoc to HTML • Merge HTML with UI and create a static site Key benefits: • Fast Node runtime and minimal dependencies • Modular and extendible
8. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 8 Creating a documentation site for users with AsciiDoc and Antora Empower your users with documentation 1. Using AsciiDoc and Antora 2. Setting up Antora 3. Summary 4.
9. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 9 Antora: Structure • Multiple independent components • Each component is identified by name and version • Each component can have multiple modules • Each module has pre-defined families for pages, images, example, attachments and partials (snippets to be included in multiple places) Advanced feature: A component can be distributed across multiple folders, branches and repositories Component Module images pages partials … …
10. Git Repo © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 10 Antora: Process What the user user does: 1. Run Antora What Antora does: 1. Load Antora playbook with list of repositories and branches 2. Clone Git repositories 3. Create HTML output from AsciiDoc 4. Merge with UI Theme and UI customizations 5. Optional: Create search index 6. Create output folder with static site Playbook Git Repo Antora Static Site UI Theme
11. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 14 Antora: Prerequisites Role Professional Skills Technical Skills Technical Infrastructure Author Writing • Git (to collborate with other authors) • AsciiDoc (to create content) • IDE w/ Git, AsciiDoc and Antora support • Node.js to run Antora for a local site preview build Docu Ops Automation • Git (for initial setup) • YAML (for configuration) • package.json (for version management) • IDE w/ Git, AsciiDoc and Antora support • CI/CD server to setup automated site publishing Web Developer Web Site Creation • HTML/CSS (to customize standard Antora Theme to blend in with existing site) • Node.js to run Antora for a local site preview build
12. © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 1. Create first component folder structure 2. Create antora.yml and give the component a name and version 3. Create create index.adoc in pages 4. Create navigation entries in nav.adoc and add it to antora.yml 5. Create playbook for authors to generate local preview site 6. Install Antora (either gloablly or using a package.json file) 7. Copy the existing UI theme (or create your own) 8. Add UI customizations 9. Create playbook for publishing the site 15 Antora: First Steps Quick Start Guide: https://docs.antora.org/antora/2.3/install-and-run-quickstart/
13. 16 Creating a documentation site for users with AsciiDoc and Antora © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz Empower your users with documentation 1. Using AsciiDoc and Antora 2. Setting up Antora 3. Summary 4.
14. Why AsciiDoc and Antora Keep your content up-to-date using collaboration as a team using version control Keep your content consistent by handling component versions and de-duplication of content Publish new features of your software in sync with documentation by best-practice CI/CD tools and automated publishing © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz Empower your users with documentation so they get their work done 17
15. Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://intellij-asciidoc-plugin.ahus1.de/ PlantUML http://plantuml.com/ https://real-world-plantuml.com/ © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 18 Links @ahus1de Antora https://antora.org/ Videos, slides and examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive https://www.ahus1.de/post/cdc-antora-live Asciidoctor Kroki extension https://github.com/Mogztter/asciidoctor-kroki
16. msg systems ag Robert-​Bürkle-Straße 1 85737 Ismaning Germany value – inspired by people Contact Alexander Schwartz Principal IT Consultant +49 171 5625767 alexander.schwartz@msg.group @ahus1de © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 19