by

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 is a single documentation component in a local 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 files 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 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.

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 site.yml at the root:

    site.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 named book.

Attributes

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

site.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.

site.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:

site.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 site.yml file and add the following content:

site.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 site.yml file and add the following content:

site.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 site.yml

Your site should be generated in the public/ directory 🚀