antora_build

This script will create a documentation site with Antora from a given source directory.

The following parameters are optional:

f

delete the output directory before site creation

o

the output directory ($PWD/build if not given)

p

path to the Antora playbook (docs/antora-playbook.yml if not given); relative to the source directory -s

s

the source directory ($PWD if not given)

The source directory needs to be a Git repository root with at least one commit.

Copy this script into your project:

<project root directory>
└── scripts
    ├── antora_build.sh
    ├── ...

See: Example

Usage

$ scripts/asciidoc/antora_build.sh
$ tree --noreport -I .git /tmp/example
/tmp/example
└── docs
    ├── antora-playbook.yml
    ├── antora.yml
    └── modules
        └── ROOT
            ├── nav.adoc
            └── pages
                └── index.adoc
$ scripts/asciidoc/antora_build.sh -s /tmp/example -o /tmp/example/build
$ tree --noreport -I .git -L 2 /tmp/example
/tmp/example
├── build
│   ├── _
│   └── example
└── docs
    ├── antora-playbook.yml
    ├── antora.yml
    └── modules

$ tree --noreport -I .git /tmp/example2
/tmp/example2
├── antora
│   └── antora-playbook.yml
└── docs
    ├── antora.yml
    └── modules
        └── ROOT
            ├── nav.adoc
            └── pages
                └── index.adoc
$ scripts/asciidoc/antora_build.sh -s /tmp/example2 -o /tmp/example2/build -p antora/antora-playbook.yml
$ tree --noreport -I .git -L 2 /tmp/example2/
/tmp/example2/
├── antora
│   └── antora-playbook.yml
├── build
│   ├── _
│   └── example
└── docs
    ├── antora.yml
    └── modules

Example

$ mkdir -p /tmp/example/scripts
$ cp scripts/asciidoc/antora_build.sh /tmp/example/scripts
$ cd /tmp/example
$ echo 'build' > .gitignore
$ git init -q
$ git commit --allow-empty -q -m initial                                  (1)
$ mkdir -p docs/modules/ROOT/pages
$ echo '= Example' >docs/modules/ROOT/pages/index.adoc
$ echo '* xref:index.adoc[]' >docs/modules/ROOT/nav.adoc
$ cat << 'EOF' >docs/antora.yml
---
name: example
version: ~                                                                (2)
nav:
  - modules/ROOT/nav.adoc
EOF
$ cat << 'EOF' >docs/antora-playbook.yml
---
content:
  sources:
    - url: ./..                                                           (3)
      start_path: docs                                                    (4)
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
EOF
$ tree --noreport -I .git /tmp/example
/tmp/example
├── docs
│   ├── antora-playbook.yml
│   ├── antora.yml
│   └── modules
│       └── ROOT
│           ├── nav.adoc
│           └── pages
│               └── index.adoc
└── scripts
    └── antora_build.sh
$ scripts/antora_build.sh
$ tree --noreport -I .git -I '*.svg' -I '*.woff' -I '*.woff2' /tmp/example/
/tmp/example/
├── build
│ ├── _
│ │ ├── css
│ │ │ └── site.css
│ │ ├── font
│ │ ├── img
│ │ └── js
│ │     ├── site.js
│ │     └── vendor
│ │         └── highlight.js
│ └── example
│     └── index.html
├── docs
│ ├── antora-playbook.yml
│ ├── antora.yml
│ └── modules
│     └── ROOT
│         ├── nav.adoc
│         └── pages
│             └── index.adoc
└── scripts
    └── antora_build.sh

⇒ build/example/index.html

1 a local content source root needs at least one commit
2 an unversioned component
3 url needs to point to the Git repository root, i.e. the directory with the .git subdirectory; this is relative to antora-playbook.yml
4 start_path points to where the component (antora.yml) can be found; relative to url

Prerequisites

More Information