https://github.com/vshn/antora-preview
Docker image used to preview Antora documentation websites locally
https://github.com/vshn/antora-preview
vshn-project-ignore
Last synced: 6 days ago
JSON representation
Docker image used to preview Antora documentation websites locally
- Host: GitHub
- URL: https://github.com/vshn/antora-preview
- Owner: vshn
- License: bsd-3-clause
- Created: 2020-09-02T13:07:05.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-05-27T21:35:41.000Z (21 days ago)
- Last Synced: 2025-05-27T22:31:20.079Z (21 days ago)
- Topics: vshn-project-ignore
- Language: Shell
- Homepage:
- Size: 134 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= 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:
[source,bash]
--
$ 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.
. Build your custom UI bundle; assuming the new file is located in `/home/user/antora-default-ui/build/custom-ui-bundle.zip`
. 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):
[source,bash]
--
$ 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:
* https://addons.mozilla.org/en-US/firefox/addon/livereload-web-extension/[Firefox]
* https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei[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.