Local Antora Plugin

Objectives

The local-antora Gradle plugin aims to:

  • generate Antora docs locally without adding a playbook

  • sensible defaults

  • work seamlessly with the local-kroki plugin

The Bootstrap Antora Task can help with the initial Antora structure.

About Antora

Antora is a documentation site generator for AsciiDoc. It’s pretty neat. Check out the Antora Docs to learn more.

This Gradle plugin aims to let you generate a site without having to care too much about how it actually works.

How It Works

The local-antora Gradle plugin applies the gradle-node-plugin and sets up the configuration for an Antora build. It will also react to the presence of the local-kroki plugin and configure Antora to use the local instance of Kroki.

The plugin:

  • adds the localAntora extension

  • applies the gradle-node-plugin

  • adds the writePackageJsonFile task, writes a package.json* file (to the project directory)

  • adds the writeAntoraPlaybookFile tasks, writes a playbook.yml* file (to the build director)

  • adds the generateLocalAntoraSite task

package.json

The writePackageJsonFile task will:

  • add scripts to install and run Antora

  • add dependencies on Antora

  • add dependencies on Antora extensions

    • defaults: asciidoctor-kroki and asciidoctor-mathjax

playbook.yml

The writeAntoraPlaybook will automatically:

  • add title

  • add start_page

  • locate the Git root as content.url

  • discover all antora.yml files and add relative start_paths

  • add HEAD as branches

  • add asciidoc.extensions

  • configure the attribute for kroki-server-url

  • configure the attribute for kroki-fetch-diagram

  • add convenience asciidoc.attributes

  • add any user defined asciidoc.attributes (default empty)

  • configure ui.bundle.url

  • configure ui.supplemental_files (default null)

Setup

build.gradle
plugins {
    id 'com.gitlab.mvik.local-antora' version '0.4.0'
}

// configure
localAntora {
    downloadNode true
    antoraVersion '^3.0.0-alpha.1'

    kroki {
    }

    playbook {
        uiBundleUrl 'https://your.org/custom-bundle.zip'
        outputSiteDir layout.buildDirectory.dir('antora-site')
    }

    playbookFile layout.buildDirectory.file('antora/playbook.yml')
}

See More Examples to get the full list of configuration options.

Run Antora

prepare Antora, run once
./gradlew nodeSetup nmpInstall
generate site
./gradlew generateLocalAntoraSite

More Examples

See use plugin examples in the source repository.