Features

A static site generator for making documentation sites from one or more versioned content repositories.

Docs as Code

Store documentation in multiple repositories

No matter how many git repositories you use, Antora can retrieve and aggregate all the content from them to assemble a documentation site.

Manage documentation versions like a pro

Use branches to version documentation just like software. Antora can find repository branches and assemble the files in each branch into a versioned documentation collection. Antora also knows how to ignore branches you don’t want published.

Workspaces that fit team and content requirements

Since documentation files can be stored in separate repositories, the teams that maintain them can use the administration policies, version schema, and release schedule that works for them.

Remote and local, private and public, bare and non-bare

Antora can collect files from a combination of local, remote public, and remote private repositories over any protocol supported by git.

Site Orchestration for Everyone

The Antora Playbook

With an Antora playbook, anyone can assemble and generate a documentation site. You don’t need any build automation or system administration knowledge to create or use an Antora playbook. A playbook is a straight-forward set of concise instructions that tells Antora what documentation to assemble, where to find it, and what UI to apply to the site.

How?

Antora runs from a purely configuration playbook project that provides instructions about what to generate and where to get it.

Run your playbook using the Antora CLI

Just point the Antora CLI at your playbook to configure and execute the default site generator. Out comes your site!

Site Remixes for Any Occasion

With Antora’s playbooks, you can control which versions of the documentation get published to a site. You can even tell Antora to use uncommitted changes when generating the site on a local machine.

Here are a few common site remixes:

  • Publish the documentation for all products and product versions to a single site.

  • Publish the documentation for each product to its own unique site with its own branded UI.

  • Only publish documentation for stable product versions to a docs site.

  • Publish a product’s beta release documentation to a private site.

  • Launch a new product’s documentation on a temporary URL with a custom UI, and, at the same time, publish it to a canonical docs site URL with your standard UI.

  • And many more …​

Open Architecture

Antora features an open architecture. Despite providing an opinionated default site generator, you’re free to reuse the core components to assemble your own custom generator pipeline.

Environment Portability

Antora automatically adapts a docs site to its publishing environment. Whether the site is published locally, to revolving testing, QA, or staging environments, or to an alternate URL for a campaign or event, the site is fully functional. This environment portability is possible because Antora’s cross referencing system isn’t based on a hardcoded base URL or system path.

Minimal markup, maximum functionality

Mark up content with AsciiDoc’s lightweight yet comprehensive syntax.

Features include:

  • Bold, italic, monospace, highlight, and custom text roles

  • Special Characters, font icons, and UI references (Ctrl+T)

  • Ordered, unordered, definition, and interactive task lists

  • Videos (self-hosted, YouTube, Vimeo) and audio with display and user-control options

  • Images and icons, inline or block, with display options

  • Tables

  • Notices (admonitions), quotes, and sidebars

  • Metadata and taxonomy

  • Cross references, in-page and page-to-page.

  • Section, block and inline IDs

  • Source code with copy and paste friendly callouts, callout icons, wrap or scroll controls, and syntax highlighting. Source code can be written in the document or sourced from another file using an include directive.

  • Include directive with tags. Select all or parts of a file and insert it into another file.

  • Table of Contents

  • Math

  • Page, section, asset, block and line controls to optimize reader experience (Rx)

No markup plugins, extensions, or shortcodes needed

AsciiDoc’s extensive feature set is available right out of the box with Antora. There’s no need to find, install, and manage plugins, extensions, or scripts to add basic capabilities to the syntax.

Tooling

Write and preview AsciiDoc with text editors and IDEs like Atom, Brackets, and IntelliJ. GitLab and GitHub render AsciiDoc files right in the browser. AsciiDoc files can also be previewed in Chrome and Firefox with the Asciidoctor extension.

Responsive maintainers

Antora’s core developers help lead the Asciidoctor organization, home of the AsciiDoc syntax and Asciidoctor, the AsciiDoc processor. Due to this direct relationship, Antora is always in sync with AsciiDoc and Asciidoctor features.

No flavor lock-in

Documentation written with AsciiDoc works with all of the software and tools in the Asciidoctor ecosystem. You don’t need to worry about incompatible syntax or lost functionality.

AsciiDoc files can also be used by other tools such as Asciidoctor PDF and EPUB, Asciidoctor HTML presentation extensions for Bespoke, Reveal.js. This means your AsciiDoc files are immediately compatible with all of the other software that uses AsciiDoc (editors, HTML presentations, Asciidoctor PDF and EPUB generators, etc.). You don’t need to worry about errors, lost functionality, or downgraded processing performance.

Extension API

Custom syntax and output transformations can be added as discrete extensions with Asciidoctor’s extension API.

Cross References

Impervious to file systems, environments, and URLs

It doesn’t matter where you publish your documentation site — on a local machine, a staging environment, or a production environment — the page-to-page cross references always work. That’s because Antora’s page referencing system isn’t coupled to filesystem paths or URLs.

Writer-friendly cross references

Writers don’t need to remember or construct the path to a file or a page’s URL. In most cases, to create a cross reference, all you need to know is the filename of the page you want to link to.

Described using AsciiDoc lists

A site’s navigation is described by one or more AsciiDoc lists that are stored alongside your documentation files. Links are added using the same cross referencing syntax used in the pages themselves. There’s no special syntax or UI template logic to learn.

No content or organization restrictions

Add normal text, images, icons, and external links to the navigation. Order and nest the links in the arrangement of your choice.

Site UI and Theme

Discrete UI

Site UIs are stored in separate repositories so that developing, testing, and publishing new or updated themes has no impact on your documentation files or their repositories. Antora retrieves the specified site UI just like it fetches the content files from their repositories.

Web team workspaces

Web teams can use their preferred repository structure, development workflow and release schedule since the site UI isn’t stored with the documentation.

Hot Swap UIs

Switch between site UIs just by changing the UI address in the playbook.

URLs and Routes

URLs for humans and SEO

A page’s URL is derived from its filename, yet still isolated from its full filesystem path.

Route and redirect controls

Routes and redirects can be specified at the site, component, version, module and page level.

Metadata and Taxonomy

Multi-level metadata controls

Add and remove metadata at the site, component, module, and page level using AsciiDoc attributes.

Built-in and custom taxonomy types

Assign taxonomy types and values at the site or page level.