vshn / antora-preview

Docker image used to preview Antora documentation websites locally

Antora Preview Tool

This tool can be used to quickly preview an Antora documentation website.

How to use

Run the following command on top of any project containing Antora documentation:

$ docker run --rm --publish 35729:35729 \
             --publish 2020:2020 \
             --volume "${PWD}":/preview/antora \
             vshn/antora-preview:$LATEST_VERSION --antora=docs --style=appuio

Passing the --help parameter shows the inline help:

Antora Documentation Previewer

This command builds an Antora documentation website locally and launches a web
server on port 2020 to browse the documentation.

Arguments:
    --style=STYLE / -s=STYLE:
           Antora UI Bundle to use to render the documentation.
           Valid values: 'vshn', 'appuio', 'syn', 'k8up', 'antora'.
           Default value: 'vshn'

    -a=PATH / --antora=PATH:
           Path to the subfolder.
           Default: 'docs'

Examples:
    antora-preview --style=appuio --antora=src

GitHub project: https://github.com/vshn/antora-preview

Open the URL http://localhost:2020 to browse the documentation.

Previewing Your Own Bundles

If you would like to use your own ui-bundle.zip file for preview, follow these steps.

1. Build your custom UI bundle; assuming the new file is located in /home/user/antora-default-ui/build/custom-ui-bundle.zip

2. Launch the previewer sharing a new volume, pointing to the location above mapped as /preview/bundles in the container, and specifying the --style parameter with the custom-ui-bundle name (this is the basename of the zip file above):

$ docker run --rm --publish 35729:35729 --publish 2020:2020 \
             --volume "${PWD}":/preview/antora \
             --volume /home/user/antora-default-ui/build/:/preview/bundles \
             vshn/antora-preview:$LATEST_VERSION --antora=docs --style=custom-ui-bundle

If needed, force refresh the page in your browser to clear any cache.

LiveReload

This image is capable of "live reloading" the documention as the user writes the Asciidoc source. To do that, you need a browser with one of these extensions:

• Firefox

• Google Chrome

Open the documentation in your browser and click on the LiveReload extension button on the toolbar; when it becomes green, the browser will automatically refresh whenever you save an Asciidoc file.