GitBook to Antora: Migration guide

gitbook-to-antora.adoc

From GitBook to Antora

The new version of GitBook dropped support for AsciiDoc, so it’s time to migrate to Antora!

Antora

Antora is a multi-repository documentation site generator for tech writers who love writing in AsciiDoc. Unlike GitBook, Antora is designed to leverage Asciidoctor to its fullest extent.

Documentation component and modules

In Antora terminology, a GitBook is a single documentation component in a local repository.

In fact, Antora works with collections of documentation that follow a standard, well-defined project structure. So the first thing you will need to do is to create a documentation component named book with a module named ROOT.

Note	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

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.

Component descriptor

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

1. 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 named index.adoc, you can remove the start_page key.

Checkout 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 CSON. In the following examples, we will be using YAML since it’s less verbose than JSON and CSON.

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. The SUMMARY.adoc file is used to generate the book’s table of contents.

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]

Example

In this guide, we will be using the "Spark Streaming Notebook" as an example. The source code of this book is available on GitHub: https://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'