I imagine you’re staring at your Ubuntu Linux [box, laptop, VM, Crostini container] and you want to publish some sweet Asciidoc docs with Antora. So, you hit the Google and land on https://docs.antora.org/antora/2.2/install/install-antora/ to find your next move. Here’s the process I followed to get a maintainable solution given some personal constraints.
Updating Node on Ubuntu
Aye, I’m on Ubuntu OS 18.04.
$ cat /etc/lsb-release | tail -n 1 DISTRIB_DESCRIPTION="Ubuntu 18.04.4 LTS"
Ubuntu 18.04 LTC has Node.js version 8 as of today. That seems ancient, and
Antora recommends the latest LTS Node. I prefer to use the distribution package
manager if available. In this case I don’t want to install and use
whack Node directly into my system
/usr/bin directory. The next best thing to
distribution packages are official PPA
Use a PPA to get the latest LTC Node
Let’s use a maintained PPA to get a more current LTS version of Node.
# Remove old versions installed with Ubuntu's package manager $ sudo apt remove nodejs nodejs-dev npm # Remove any other node packages $ sudo apt autoremove # WARNING: never just pipe something from the internet into sudo. # Check the setup script carefully before you run the next command. # # Install LTS node $ curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - # The big moment $ sudo apt install nodejs # Check that the versions are correct $ node -v v12.14.1 $ npm -v 6.13.4
Set a local directory for Node modules
Installing node packages into
/usr/lib/node_modules would require
creates unmaintained cruft in your file system. Antora docs suggest an
alternative of installing its Node packages in a document
but this seems like it would have to be redone for each doc project directory,
and then you have to maintain it individually. Also, you have to prefix the path
every time you run antora.
Let’s use a directory in our home directory and tell
npm that this is now the
global directory for this user. We’ll update our path to find these packages in
First, let’s set the package directory and update the
npm config file.
# Create a home directory for node packages $ export NPM_PACKAGES="$HOME/.npm-packages" $ mkdir -p $NPM_PACKAGES $ echo "prefix = $NPM_PACKAGES" >> ~/.npmrc
Update your Bash .profile
I adapted some instructions that I found at
Add this code to your
# NPM packages in homedir NPM_PACKAGES="$HOME/.npm-packages" # Tell our environment about user-installed node tools if [ -d "$NPM_PACKAGES/bin" ] ; then PATH="$NPM_PACKAGES/bin:$PATH" fi # Unset manpath so we can inherit from /etc/manpath via the `manpath` # command if [ -d "$NPM_PACKAGES/share/man" ] ; then unset MANPATH # delete this if you modified MANPATH elsewhere # in your environment MANPATH="$NPM_PACKAGES/share/man:$(manpath)" fi # Tell Node about these packages if [ -d "$NPM_PACKAGES/lib/node_modules" ] ; then NODE_PATH="$NPM_PACKAGES/lib/node_modules:$NODE_PATH" fi
Let’s do it.
-g is for global, y’all.
$ npm i -g @email@example.com @firstname.lastname@example.org [lots of output]
Source your new Bash profile and run Antora
# Set environment variables and update your path $ source ~/.profile # Did it work? How are you feeling? $ antora version 2.2.0
Photo credit: Negative Space from Pexels