Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Creating a documentation site for users with AsciiDoc and Antora

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.

Alexander Schwartz

December 08, 2020
Tweet

More Decks by Alexander Schwartz

Other Decks in Programming

Transcript

  1. Creating a documentation site for users
    with AsciiDoc and Antora
    Alexander Schwartz, Principal IT Consultant
    Jfokus Brown Bag Session, 2020-12-10

    View full-size slide

  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.

    View full-size slide

  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

    View full-size slide

  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.

    View full-size slide

  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

    View full-size slide

  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/

    View full-size slide

  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

    View full-size slide

  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.

    View full-size slide

  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
    … …

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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/

    View full-size slide

  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.

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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
    [email protected]
    @ahus1de
    © msg | December 2020 | Creating a documentation site for users with AsciiDoc and Antora | Alexander Schwartz 19

    View full-size slide