Antora

Documentation Sites for Software Teams

A static site generator for docs

Antora Markup

= AsciiDoc

The *M* in JAM stands for *Markup*.
In Antora, the markup is AsciiDoc.
Antora uses Asciidoctor.js to process the AsciiDoc.

== Why AsciiDoc?

AsciiDoc is lightweight, yet semantically rich.
And it can be easily extended to add more functionality.

If you want to write documentation using lightweight markup,
AsciiDoc is the way to go!

Authoring: AsciiDoc

Publishing: Antora

screenshot couchbase docs — https://docs.couchbase.com

screenshot rudder docs — https://docs.rudder.io

screenshot mulesoft — https://docs.mulesoft.com

Vision 🔭

[docs] as {code}

Docs are integral

Documentation is the “curb appeal” of software

[docs] as {code}

To produce documentation by sharing conventions, processes, and tools from software development.

Features 📸

Distributed
content

Standard
structure

Multi-repo static site generator

playbook.yml

site:
  title: Couchbase Docs
  url: https://docs.couchbase.com
  start_page: home::index.adoc
content:
  branches: release/*
  sources:
  - url: .
    branches: HEAD
    start_path: home
  - url: https://github.com/couchbase/couchbase-operator.git
    start_path: docs/user
  - url: https://github.com/couchbase/docs-server.git
...

Standard Project Structure

Component
repositories

Version
branches

Versions stored in branches

antora.yml

name: server
version: '6.0'
title: Couchbase Server
start_page: introduction:intro.adoc
nav:
- modules/ROOT/nav.adoc

Source-to-source
references

Ubiquitous
preview

Content
UI

Dedicated
UI project

Shared
UI bundle

Developed independently
Common style across products
Fully customizable

playbook.yml

...
ui:
  bundle:
    url: https://github.com/couchbase/docs-ui/.../ui-bundle.zip

Dev-friendly
tools

DevOps
practices

page.adoc

= Topic Title

Content is written in plain text.
No XML or HTML is required.

== Subject A

.Screenshot
image::screenshot.png[]

== Subject B

TIP: AsciiDoc supports various content types.

nav.adoc

* xref:overview.adoc[Overview]
* xref:whats-new.adoc[What's New]
* Install
 ** xref:install:requirements.adoc[Requirements]
 ** xref:install:index.adoc[Install Application]
* Run
 ** xref:run:index.adoc[Run Application]
 ** xref:run:cli-reference.adoc[CLI Reference]

Demo 🍿

Wrap-Up

Antora integrates documentation production into an existing agile development workflow.

Thank You!

antora.org

Slides & Transcript: gitlab.com/opendevise/talks/docs-sites-for-software-teams/tree/devoxxuk-2019