Blog

by
Guillaume Grossetie

Awesome Antora: Migrate from GitBook to Antora

As you may already know, the new version of GitBook has dropped support for AsciiDoc. And since you’re here, you probably enjoy writing documentation in AsciiDoc and you want to keep using it! I have good news for you and it’s called Antora.

Antora

Antora is a documentation site generator and AsciiDoc is Antora’s native content markup language. OpenDevise, the company behind Antora, is also actively working on Asciidoctor, the reference implementation of the AsciiDoc syntax.

In other words, the AsciiDoc syntax is a first class citizen in Antora and Asciidoctor is used at its full potential.

Without further ado, let’s migrate from GitBook to Antora!

Documentation component and modules

A collection of documentation files organized under Antora’s standard project structure is called a documentation component.
In Antora’s terminology, a GitBook corresponds to a single documentation component in a single git repository.
So the first thing you will need to do is to create a documentation component named book with a module named ROOT.

Here the module named ROOT will contain everything, but depending on your use case you could create as many modules (or documentation components) as you want.

  1. Create the structure

    $ mkdir -p book/modules/ROOT/pages

  2. Move every *.adoc file to pages

    $ mv *.adoc book/modules/ROOT/pages

If you have images, attachments or videos, you will need to create the following subdirectories in your module:

  • assets/attachments

  • assets/images

  • assets/videos

And here’s the complete tree structure:

.
└── book
    └── modules
        └── ROOT
            ├── assets
            │   ├── attachments
            │   ├── images
            │   └── videos
            └── pages

8 directories

If your book is structured in chapters, you do not necessarily need to create a module for each chapter. You can instead create ’topic’ subfolders in the pages directory.

Next, we need to describe our documentation component.

Component descriptor

A documentation component must contain a component descriptor file named antora.yml.

So let’s create a file named antora.yml in the book/ directory:

book/antora.yml
name: book
title: Book
version: 'latest'
start_page: ROOT:overview.adoc

The keys and values are pretty much self explanatory. Our component will be named book, its title will be Book and its version will be latest.

We also explicitly define the start page. By default, Antora looks for a file named index.adoc in the ROOT module. So if your start page is already named index.adoc, you can remove the start_page key.

The name of the component is determined from the name key in the component descriptor. In this migration guide, the component root directory is named book but this does not affect the name of the component (defined in the component descriptor file).

Check out the component description documentation to learn more.

Playbook

GitBook allows you to customize your book using a configuration file named book.json.
Similarly, Antora uses a playbook file to control what content is included in your site, what user interface (UI) is applied to it, and where the site is published.
Playbooks can be written in YAML, JSON, and TOML.

In the following examples, we will be using YAML (but you’re free to use JSON or TOML):

Content

In the previous section we’ve created a documentation component called book. The next step is to register this documentation component in our playbook.

  1. Create a file named antora-playbook.yml at the root of your git repository:

    antora-playbook.yml
    content:
  sources:
  - url: .
    start_path: book

Since we are working with a local repository we are using the value dot (.).
The path will be resolved relative to the location of the playbook file.

The start_path value points to our documentation component located in the book directory (and also named book).

For ease of migration, this guide is recommending a particular very simple, but restrictive, layout in a single git repository. In a playbook sources entry, there are two keys expressing the relationship between the playbook, the git repository of the source, and the location of the component descriptor. For a local repository, the url will be the path from the playbook to the root of the git repository. The start_path is the path from the root of the git repository to the antora.yml component descriptor.

Attributes

The attributes key in your playbook file can be used to define global (i.e. site-wide) AsciiDoc document attributes.

antora-playbook.yml
asciidoc:
  attributes:
    spark-version: '2.1.0'
    sourcedir: 'src/main/scala'

Google Analytics

Antora has built-in support for Google Analytics. To enable it, you will need to configure your key in site.keys.google_analytics.

antora-playbook.yml
site:
  keys:
    google_analytics: 'UA-86782445-4'

Navigation

With Antora, you can create your site’s navigation with AsciiDoc and store it right alongside your documentation files.

GitBook uses a SUMMARY.adoc file to define the structure of chapters and subchapters of the book. Here’s an example:

= Summary

. link:part1/README.adoc[Part I]
.. link:part1/writing.adoc[Writing is nice]
.. link:part1/antora.adoc[Antora is nice]
. link:part2/README.adoc[Part II]
.. link:part2/feedback_please.adoc[We love feedback]
.. link:part2/better_tools.adoc[Better tools for authors]

In Antora, you need to define the key nav in the antora.yml file:

  1. Edit the file antora.yml in the book/ directory:

    book/antora.yml
    name: book
title: Book
version: 'latest'
start_page: ROOT:overview.adoc
nav:
- modules/ROOT/nav.adoc

    The nav key accepts a list of navigation files. Each value specifies the path to a navigation file (e.g., modules/module-name/nav.adoc). The order of the values dictates the order the contents of the navigation files are assembled in the published component menu.

  2. Create a file named nav.adoc in the book/modules/ROOT directory:

    book/modules/ROOT/nav.adoc
    .xref:index.adoc[In-module page]
* xref:a-page-in-this-module.adoc[Another in-module page]
** xref:another-page.adoc#and-fragment[An in-module page deep link]
* xref:topic/page.adoc[In-module page in a topic folder]

Links between pages

If you use the published URL in your links, I would recommend to start using cross-references. In Antora, you can create a link between pages using the xref macro. For instance, to create a link to a page in the same module, you should use:

xref:error-handling.adoc[Error Handling]

And here’s the syntax to create a link to a page in a topic folder:

xref:concept/index.adoc[Key Concepts]

As we’ve seen before images are stored in a directory named assets/images. To insert an image, we need to use the AsciiDoc block image macro (image::[]). Let’s say we have an image called pipeline-workflow.png in assets/images. Here’s the syntax to add it to a page.

image::pipeline-workflow.png[a diagram illustrating the pipeline stages]

As you can see, we don’t need to use a relative path or to define the imagesdir. So in most cases, you should be able to simplify the path to your linked resources.

Example

We will be using the "Spark Streaming Notebook" as an example. The source code of this book is available on GitHub: github.com/jaceklaskowski/spark-streaming-notebook

Here’s the book.json file:

book.json
{
  "structure": {
    "readme": "book-intro.adoc"
  },
  "variables": {
    "spark.version": "2.1.0",
    "sourcedir": "src/main/scala"
  },
  "plugins": ["ga"],
  "pluginsConfig": {
    "ga": {
      "token": "UA-86782445-4"
    }
  }
}

And here’s the equivalent configuration in Antora:

antora-playbook.yml
site:
  title: Spark Streaming
  url: https://jaceklaskowski.github.io/spark-streaming-notebook
  start_page: book::intro.adoc
  keys:
    google_analytics: 'UA-86782445-4'
content:
  sources:
  - url: .
    start_path: book
asciidoc:
  attributes:
    spark-version: '2.1.0'
    sourcedir: 'src/main/scala'

Generate your site

To get you started quickly, Antora provides a default UI. To use it, edit your antora-playbook.yml file and add the following content:

antora-playbook.yml
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Then, configure the output directory to define where the generated site will be published. Again, edit your antora-playbook.yml file and add the following content:

antora-playbook.yml
output:
  dir: ./public

We’re almost done. If that’s not already the case, please install Antora on your machine. Then, open a terminal and type:

$ antora antora-playbook.yml

Your site should be generated in the public/ directory 🚀