Multi Repository Documentation

Contents

• Introduction
• Requirements
• Setup
• Wrapping Up
• Conclusion
• Share Support

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:

• Node.js
• git
• Gulp CLI

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.