Antora Quick Start

Antora Quick Start

To quote Antora website:

[Antora is] The multi-repository documentation site generator for tech writers who writing in AsciiDoc.

It is also used by Fedora Project

Here is step by step guide how to install it on Fedora 33 and generate demo web site.

Setup

Tested OS: Fedora 33

NOTE: All commands should be entered as non-privileged user under whom you plan to use Antora. Also you should have configured properly sudo for such user to run some commands under root when needed.

Ensure that you have SELinux disabled or in permissive mode:

$ /usr/sbin/sestatus
SELinux status:                 disabled

Otherwise you may run into troubles (in worst case you would need to label all files under ~/public_html to right SELinux type - which is beyond scope of this article).

Setting up Apache

We need some web-server to serve web content generated by Antora. I decided to use Apache with Home-Dirs feature.

To install Apache under Fedora 33 just issue:

sudo yum install httpd

Ensure that TCP/http access is allowed on firewall:

sudo firewall-cmd --add-service=http
sudo firewall-cmd --permanent --add-service=http

Enable userdir module - change /etc/httpd/conf.d/userdir.conf this way:

diff -u ./etc/httpd/conf.d/userdir.conf{.orig,}
--- ./etc/httpd/conf.d/userdir.conf.orig        2020-11-28 10:50:18.137370935 +0100
+++ ./etc/httpd/conf.d/userdir.conf     2020-11-28 10:50:30.761432763 +0100
@@ -14,14 +14,14 @@
     # of a username on the system (depending on home directory
     # permissions).
     #
-    UserDir disabled
+    #UserDir disabled

     #
     # To enable requests to /~user/ to serve the user's public_html
     # directory, remove the "UserDir disabled" line above, and uncomment
     # the following line instead:
     #
-    #UserDir public_html
+    UserDir public_html
 </IfModule>

Now enable and start httpd service:

sudo systemctl enable httpd
sudo systemctl start httpd

Finally we will test that userdir feature really works. To setup userdir and put sample web content here do this - as non privileged user where you will play with Antora:

# Ensure that Apache can enter $HOME directory
chmod a+x ~
# Apache's module `userdir` expects content here:
mkdir ~/public_html
echo "<h1>Hello from $USER</h1>" > ~/public_html/index.html

Now point your browser:

• http://IP_OF_YOUR_SERVER/~USER/
• where replace
  • IP_OF_YOUR_SERVER - IP address of your web server
  • USER - username of non-privileged user where you prepared above index.html file.
• in my example I use URL: http://192.168.0.101/~ansible/

WARNING!

Some recent browsers are so crappy that they my change http:// to https:// and hide actual protocol without your permission!!! Welcome to future!

WARNING!

If you get error 403 Forbidden it is likely that you have enabled SELinux. You can try this remedy:

 sudo setsebool -P httpd_enable_homedirs 1

To see more information on these configuration options under SELinux do this:

• install manual pages:

  sudo yum install selinux-policy-doc

• to see what SELinux settings are available for Apache, use this command:

  man httpd_selinux

Installing Antora

Now back installing Antora - we may (mostly) follow official docs

At first install nodejs and npm (both are included in Fedora 33):

sudo yum install npm nodejs git-core

Reconfigure NPM so it will use local user's directory for installation:

npm config set prefix ~/.my-npm

Finally install antora 2.3 using:

npm i -g '@antora/[email protected]' '@antora/[email protected]'

To have antora executable on your PATH add to your ~/.bashrc

# User specific aliases and functions
export PATH=~/.my-npm/bin:$PATH

Update your current path using:

source ~/.bashrc

And test that antora command works:

$ antora -v
2.3.4

Generate Demo site with Antora

Now we will generate web pages from official Demo site from Antora authors:

mkdir -p ~/projects
cd ~/projects
git clone https://gitlab.com/antora/demo/docs-site.git
cd docs-site

And now tough stuff - generate demo web-site pages:

$ antora generate --to-dir ~/public_html/demo antora-playbook.yml

[clone] .../antora/demo/demo-component-a.git [#################################]
[clone] .../antora/demo/demo-component-b.git [#################################]

Now you can point to browser to above URL where you just append /demo/ in path, in my example.

• http://192.168.0.101/~ansible/demo/

You should see website similar to picture below:

Done!

More examples

Here are few examples that I plan to study:

• whole Fedora web site, there are two branches:
  • stage: https://pagure.io/fedora-docs/docs-fp-o/tree/stg
  • production: https://pagure.io/fedora-docs/docs-fp-o/tree/prod
• lisk docs:
  • https://github.com/LiskHQ/lisk-docs
• Couchbase tutorials and templates:
  • https://github.com/couchbase/tutorials
  • https://github.com/couchbaselabs/tutorial-template

Opinions

Here is very nice review on Antora and other documentation tools:

• https://evaparish.com/blog/2018/10/19/antora-and-docusaurus-duke-it-out
• https://evaparish.com/blog/2018/10/19/in-which-i-vent-more-about-antora
• https://evaparish.com/blog/2018/10/19/why-sphinx-and-rst-are-the-best

All three articles are worth reading!