Contents
Introduction
Hey there! I'm Francesco known as Airscript on the web.
Today I want to share with you how to use Antora, a tool for managing multi repository documentations.
In this blog post we'll see what's required to run an Antora project and how actually you can spin up one too!
Requirements
Before even starting the next section, be sure to have installed on your machine the following requirements:
Since we'll be using Antora 3, the suggested versions for Node.js runtime are spacing between 16 and 18 LTS.
Be sure to type node -v
inside your terminal of choice to check which version you have.
Setup
After you got all the requirements, we can start making our multi repository documentation.
In this article I'll be covering a multi repository where we have split up the actual documentation and the UI used to present it.
UI
Let's start from the UI. In order to use it, we can just clone the base template offered by Antora:
$ git clone https://gitlab.com/antora/antora-ui-default.git documentation-ui
In this default UI, you'll find a folder structure comprehensible of various sections such as one for previewing your UI changes and so on.
Contents
After looking at the UI, we can practically move onto the actual repository for the documentation.
For this post we'll be using two demo documentations made by Antora, written in AsciiDoc.
You can simply modify those to your needs after all.
$ git clone https://gitlab.com/antora/demo/demo-component-a.git documentation-1
$ git clone https://gitlab.com/antora/demo/demo-component-b.git documentation-2
Now we have two documentations to add to our previously built UI.
Wrapping Up
Now that you have a fully scaffolded multi repository documentation, we have to wrap things up together.
Just for ease of use, we'll be making a dedicated repository that will contain the actual documentation holding both UI and contents.
In this repository we only need a playbook that will link everything up.
This playbook we'll be needed by antora
CLI.
Let's start creating a documentation-playbook.yml
file with contents like this one in it:
site:
title: Antora Documentation
url: <documentation-url>
start_page: documentation::index.adoc
content:
sources:
- url: <documentation-1-url>
- url: <documentation-2-url>
ui:
bundle:
url: <documentation-ui-bundle-url>
snapshot: true
output_dir: assets
output:
clean: true
dir: ./docs
And to generate the actual final result, we only have to install antora
CLI and run a simple command:
$ npm install -g antora
$ antora documentation-playbook.yml
# If you don't want to install globally antora, this is an alternative with npx.
$ npx antora documentation-playbook.yml
This command will generate our bundle inside docs
folder and basically that's it.
You only have to deploy it wherever you want to.
Conclusion
After almost 5 repositories we managed to compose up a multi repository documentation: starting from UI, content and actual bundle repository.
This tool is suggested to who wants to build products with multiple versions or a hub of documentations encapsulated in their own repository.
In case you want something lighter and easier, just take a lighter tool like Docusaurus.
Share Support
If you have liked this post, just come and tell me!
Are you too shy for doing this? No problem. Just visit airscript.it and share your support following me on your preferred social platform.
If you want to make me even happier, just follow, share or star me and my projects on GitHub.
Top comments (0)