-
Notifications
You must be signed in to change notification settings - Fork 8
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.
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).
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 aboveindex.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://
tohttps://
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 1To 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
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
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!
Here are few examples that I plan to study:
- whole Fedora web site, there are two branches:
- lisk docs:
- Couchbase tutorials and templates:
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!
Copyright © Henryk Paluch. All rights reserved.
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License