Antora is a modular, multi-repository site generator designed for creating documentation sites from content composed in AsciiDoc and processed with Asciidoctor.
Antora’s toolchain and workflow help documentation and engineering teams create, manage, collaborate on, remix, and publish documentation sites sourced from multiple versioned git repositories without needing expertise in web technologies, build automation, or system administration.
This project includes a command line interface (CLI) and a preassembled site generator pipeline so you can quickly start publishing documentation sites with Antora.
This section offers a basic tutorial for evaluating Antora. More comprehensive installation instructions are in the Antora documentation.
Antora is built on Node.js and is verified to work on Linux, macOS, and Windows.
To install Antora, you’ll need Node (including npm, which is bundled with Node) on your system.
You may also find the base build tools for your OS helpful (which includes git), though they’re not required.
We recommend using the latest long term support (LTS) release of Node.
While you can use other versions of Node, Antora is only tested against active LTS releases.
To check whether you have Node installed, and which version, open a terminal and type:
$ node --version
If this command fails with an error, it means you don’t yet have Node installed. If the command doesn’t report an active Node LTS version (e.g., v12.13.0), you don’t have a suitable version of Node installed.
The best way to install Node is to use nvm (Node Version Manager). If your package manager provides Node and npm packages, and you’re familiar with using the tools installed system-wide, you may choose to go that route. However, we believe you’ll be more successful if you choose nvm.
|
Note
|
Most CI environments use nvm to manage the version of Node used in the build job. By using nvm, you align your local setup with the environment used to generate and publish your production site. |
If you’re using Linux or macOS, follow the nvm installation instructions to set up nvm on your machine.
If you’re using Windows, you can install the Windows port of nvm via the Chocolatey package manager using choco install -y nvm.
Alternatively, you can install the LTS release of Node directly using choco install -y nodejs-lts.
Once you’ve installed nvm, open a new terminal and install the latest Node LTS release using:
$ nvm install --lts
|
Important
|
If you’re using nvm for Windows, you must enter the full version of Node when running commands (e.g., nvm install 12.13.0, nvm use 12.13.0).
Run nvm list available to see a list of available Node versions.
|
To make Node 12 the default in new terminals (Linux and macOS only), type:
$ nvm alias default 12
Switch to this version of Node using the following command:
$ nvm use 12
Now that you have Node installed, you can install Antora.
To generate a site with Antora, you need the Antora CLI and an Antora site generator pipeline.
Once these packages are installed, you use the antora command to generate your site.
To install these packages globally using npm, in your terminal, type:
$ npm install -g @antora/cli @antora/site-generator-default
Verify the antora command is available on your PATH by running:
$ antora -v
For more installation methods and details see the installation documentation. Now that Antora is installed, you’re ready to set up a playbook and generate a documentation site.
To generate a site with Antora, you need a playbook file that points to at least one content source repository and a UI bundle. The Antora Demo repositories are set up as an Antora documentation project, so we can use them for now as your content sources. Antora also provides a default UI for you to use out of the box.
First, create a new directory for your site and switch to it. Next, add a playbook file named antora-playbook.yml and populate it with the configuration in the following example. Alternatively, you can download the playbook file from the Antora demo site’s playbook repository.
site:
title: Antora Demo Site
url: https://my-antora-demo-site.org
start_page: component-b::index.adoc
content:
sources:
- url: https://@gitlab.com/antora/demo/demo-component-a.git
branches: master
- url: https://gitlab.com/antora/demo/demo-component-b.git
branches: [v2.0, v1.0]
start_path: docs
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: trueWe’re using Antora’s default UI as the UI for the site. Antora will take care of assembling all this input together to produce a documentation site.
The UI bundle can be loaded from a URI or a local filesystem path. If you want to use your own UI bundle, follow the instructions in the README for the Default UI.
To generate the site, simply point the antora command at your playbook file.
In your terminal, type:
$ antora antora-playbook.yml
Antora will clone the content repository, convert the AsciiDoc pages to embeddable HTML, wrap the HTML in a page template from the UI, then assemble the pages together along with the assets into the destination folder, which defaults to build/site.
To view your site, navigate to any HTML page inside the destination folder in your browser. Using this example, look for the entry point file build/site/index.html. That file will redirect you to the start page. A site generated by Antora is designed to be viewable with or without a web server.
If something goes wrong during generation, you’ll see an error message in the terminal.
If this message does not provide enough information to fix the problem, you can ask Antora for more context.
To tell Antora to reveal the calls leading up to the error (i.e., the stacktrace), run the antora command again, this time with the --stacktrace option:
$ antora --stacktrace antora-playbook.yml
Share this stacktrace when asking for help.
If any of your content repositories require authentication, Antora will look up the credentials in the default git credential store file or one that you specify using the --git-credentials-path CLI option.
See the private repository authentication documentation to learn more.
Antora is designed to help you easily write and publish your documentation. However, we can’t fully realize this goal without your feedback! We encourage you to report issues, ask questions, share ideas, or discuss other aspects of this project using the communication tools provided below.
Activity drives progress! To that end, the issue tracker is king.
The preferred means of communicating problems, ideas, and other feedback is through the project issue tracker.
-
Issue tracker (GitLab)
Any significant change or decision about the project must be logged there.
If you need to switch to real time input, you may be interested in visiting one of the chat rooms. We’ve set up two chat rooms for discussing Antora. Choose the one that best suits your needs.
-
antora/users (Gitter) — Community support for Antora users.
-
antora/dev (Gitter) — Discussions involving the development of Antora.
Keep in mind that the discussion logs for these rooms are archived, but there is no guarantee those logs will be saved indefinitely.
If you want to share your experience with Antora or help promote it, we encourage you to post about it on social media. When you talk about Antora on Twitter, you can mention the official account for the project:
-
@antoraproject — The official Antora account on Twitter.
You can also use the #antora hashtag to help promote the project or discover other people talking about it.
If you decide you want to get involved to help improve the project, then you’ll be interested in the information provided in the Contributing section.
If you are interested in contributing to this project, please refer to the contributing guide. In this guide, you’ll learn how to:
Thanks in advance for helping to make this project a success!
The Antora core components include a default site generator package, the packages the default site generator delegates to, and a CLI package. These packages are released together and follow semantic versioning rules (major.minor.patch). Major versions are maintained for at least 1 year after the initial public stable release. Only the latest minor release will receive patch releases.
Copyright © 2017-2020 by OpenDevise Inc. and the individual contributors to Antora.
Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE to find the full license text.
Development of Antora is led and sponsored by OpenDevise.