Container
Docker / Podman
You don’t need to install one of the third-party-programs like dblatex, Apache FOP, Lilypond, ePubcheck … You don’t even need a Python interpreter.
The AsciiDoc3-container is extremely usefull for Windows users since Windows lacks dblatex, lxml2, source-highlight, xmllint, graphviz … And no hassle with cygwin.
GNU/Linux users may benefit from Docker, too: all third-party programs wait in the wings.
AsciiDoc3 provides two out-of-the-box images on Docker Hub: latest (= default = full) and small. Learn more.
See here for the differences. If you prefer the small image, replace latest with small when running through the following steps.
Let’s start the AsciiDoc3 docker experience right now! Follow the steps described below.
Quickstart
You want to start in a few seconds? Take a look at this quickstart. More details are given below.
The next section is for GNU/Linux users - Windows starts here.
Quickstart GNU/Linux
(install docker)
mkdir /home/$(whoami)/asciidoc3_docker
cd /home/$(whoami)/asciidoc3_docker wget https://asciidoc3.org/docs/download/asciidoc3-latest.tar.gz
tar -xzf asciidoc3-latest.tar.gz -C ~/asciidoc3_docker rm asciidoc3-latest.gz docker run --name asciidoc3_docker --hostname='asciidoc3_host' \ --cpus='1.0' --memory 1024m \ --volume /home/$(whoami)/asciidoc3_docker/:/home/ad3docker/:Z \ --user $(id -u) --rm asciidoc3/asciidoc3:latest \ ./asciidoc3.py -a toc -a icons -n doc/test.txt
| Installing docker is beyond the scope of this site. |
| Don’t forget sudo usermod -aG docker $USER and logout/login. |
| You may choose another unique name instead of asciidoc3_docker. |
| $(whoami) is of course your username. |
| ✅ Yes! The tarball works also with Docker. |
 | This is an oneliner. Be careful to provide the correct path and directories. |
Allow about 12s for downloading and extracting the image … but only one-time at the first time!
This is a pretty long command. You may shorten this tapeworm.
Podman
asciidoc3_docker works with podman, too! We tested this with a fedora machine.
All information given on this page about docker is valid in an analogue way.
In most cases all you need to do is to replace the docker command with podman.
|
Yes, that’s all! It works! Open the result with your browser: /home/$(whoami)/asciidoc3_docker/doc/test.html Continue with bash-scripting or Next Steps. |
Quickstart Windows
(install docker)
| Installing docker is beyond the scope of this site. |
Open the PowerShell as a normal (non-Admin) user:
PS C:\Users\<username>: mkdir $env:UserProfile\asciidoc3_docker
| You may choose another unique directory instead of asciidoc3_docker. |
Now we have to open a PowerShell as admin since we have to download a file and add some symlinks:
cd C:\Users\<username>\asciidoc3_docker
| Replace <username> with your username. |
| Or download here: Download Container (Docker/Podman) |
| ✅ Yes! The setup.exe works also with Docker. |
Install the exe in the usual way into folder asciidoc3_docker.
If the symlinks are not present after this step, you may add them manually.
Strictly speaking symlinks are not mandatory. You may add/copy the images/icons manually to the appropriate location (the folder images).
(admin rights) (remove items if they exists before adding the symlink) Remove-Item asciidoc3.conf, if it exists New-Item -ItemType SymbolicLink -Name asciidoc3.conf -Target conf\asciidoc3.conf Remove-Item doc\images New-Item -ItemType SymbolicLink -Name images -Target doc\images Remove-Item conf\backends\text.conf New-Item -ItemType SymbolicLink -Name conf\text.conf -Target conf\backends\text.conf Remove-Item filters\music\images New-Item -ItemType SymbolicLink -Name images -Target filters\music\images Remove-Item filters\graphviz\images New-Item -ItemType SymbolicLink -Name images -Target filters\graphviz\images Remove-Item filters\music\images New-Item -ItemType SymbolicLink -Name images -Target filters\music\images
You can execute this with one line:
(admin rights)
Remove-Item asciidoc3.conf; New-Item -ItemType SymbolicLink -Name asciidoc3.conf -Target conf\asciidoc3.conf; Remove-Item doc\images; New-Item -ItemType SymbolicLink -Name images -Target doc\images; Remove-Item conf\backends\text.conf; New-Item -ItemType SymbolicLink -Name conf\text.conf -Target conf\backends\text.conf; Remove-Item filters\music\images; New-Item -ItemType SymbolicLink -Name images -Target filters\music\images; Remove-Item filters\graphviz\images; New-Item -ItemType SymbolicLink -Name images -Target filters\graphviz\images; Remove-Item filters\music\images; New-Item -ItemType SymbolicLink -Name images -Target filters\music\images
We don’t need Admin rights to start a container, if you configured docker in this way: Docker without admin rights.
But you may of course start the container as admin, there is no risk here.
PowerShell as normal User
PS C:\Users\<username>\asciidoc3_docker docker run --volume C:\Users\<username>\asciidoc3_docker\:/home/ad3docker/ --rm --network none asciidoc3/asciidoc3:latest ./asciidoc3.py -a toc -a icons -n doc/test.txt
| Replace <username> with your username. |
| This may take a while (15s) … |
(… downloading and extracting the image from hub.docker.com) … but only one-time at the first time! This is a pretty long command. You may shorten this tapeworm, look here!
|
|
Yes, that’s all! It works! Open the result with your browser: C:\Users\<username>\asciidoc3_docker\doc\test.html Continue with Scripting or Next Steps. |
Manual
Prerequisites, Installing Docker
First - you guessed it - you need Docker. Look at the in-depth installation guide.
-
GNU/Linux: user has to be member of group docker.
You have to do something like sudo usermod -aG docker $USER -
Docker runs on Windows 10/11.
A non-admin user needs permission to start a container: search the web for somthing like windows 11 docker user permission.
Docker seems to be well integrated in the Windows ecosystem in the meantime. -
Check your installation by running docker version or start your docker experience with docker run hello-world.
GNU/Linux
AsciiDoc3 needs some configuration files. To adjust them to your needs they have to be outside the container. And of course you want to edit and provide your input file and the asciidoc3/a2x3-command with some options. And you would like to see the output, don’t you?
These things are mounted to the container using the option --volume.
Directories
To keep your system clean it is strongly recommended to create an own directory for asciidoc3_docker:
mkdir /home/$(whoami)/asciidoc3_docker
AsciiDoc3 Docker Tarball
See above quickstart.
|
Please keep in mind: Write your own input inside the folder asciidoc3_docker - the container can’t see any file outside this folder! |
Bash-Scripting
Of course it’s not a good idea to type docker run --name asciidoc3_docker … --rm asciidoc3/asciidoc3:latest every time you want to start the program. That’s a job for ./bashrc: nano ~/.bashrc
Go to the end of the file and add the following line:
function ad3 { docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume /home/$(whoami)/asciidoc3_docker/:/home/ad3docker/:Z --user $(id -u) --network none --rm asciidoc3/asciidoc3:latest $@; }
| One line, note the $@; } (dollar at semicolon space curly bracket) at the end. |
To make this applicable
source ~/.bashrc
From now on start the container like so
ad3 ./asciidoc3 -a toc -a icons -n doc/test.txt
Continue with Next Steps.
Windows
Installing
There’s almost nothing to add to the steps described in quickstart. So here are some hints:
-
AsciiDoc3 needs some configuration files. To adjust them to your needs they have to be outside the container. They are mounted to the container using the option --volume.
-
To keep your system clean it is highly recommended to create an own directory for asciidoc3_docker: mkdir $env:UserProfile\asciidoc3_docker
|
|
Please keep in mind: Write your own input inside the folder asciidoc3_docker - the container can’t see any file outside this folder! |
PowerShell Function / Scripting
Of course it’s not a good idea to type docker run --name asciidoc3_docker … --rm asciidoc3/asciidoc3:latest every time you want to start the program. That’s a job for a PowerShell function:
PowerShell as Normal User
PS C:\Users\<username>\asciidoc3_docker> function ad3(){ docker run --name asciidoc3_docker --hostname='asciidoc3-host' --cpus='1.0' --memory 1024m --volume C:\Users\<username>\asciidoc3_docker\ad3files:/home/ad3docker --network none --rm asciidoc3/asciidoc3:latest $args }
| One long line. Replace <username> with your username. |
From now on you can execute the container much easier:
ad3 asciidoc3 -a toc -a icons -n doc/test.txt
The function ad3 is gone and no longer available when closing the PowerShell. To get the function loaded permanently add it to your PowerShell profile. To start with profiles you may take a look here.
Continue with Next Steps.
MacOS
The AsciiDoc3 container should run on this platform, too.
Next Steps
Assuming you have arranged ad3 as an alias for docker run … asciidoc3/asciidoc3:latest, here are some use cases for your new asciidoc3-container.
mytext.txt lives in directory asciidoc3_docker.
Produce a PDF
ad3 a2x3 -f pdf --fop mytext.txt
| Option --fop is mandatory when using image small: there is no dblatex installed. |
Use a source-highlighter
ad3 asciidoc3 doc/source-highlight-filter.txt
Use math formula
ad3 asciidoc3 -a asciimath -a toc -n -a icons ./doc/asciimathml.txt
You can find more exemples in folder tests/data, e.g.
ad3 asciidoc3 tests/data/newtables.txt
If you want to see how AsciiDoc3 works, you may add the -v (--verbose) option, like so
ad3 asciidoc3 -v tests/data/filters-test.txt
ad3 asciidoc3 doc/slidy-example.txt
And after that, take a look in the userguide.
Docker Run, Images, Dockerfile
Explore docker run … asciidoc3/asciidoc3:latest
docker run \ # Start new container from image asciidoc3/asciidoc3
--name asciidoc3 \ # Give a name to the container: optional
--hostname='asciidoc3-host' \ # Give a name to the host-container: optional
--cpus='1.0' \ # Secureness: Limit usage of cpu: optional
--memory 1024m \ # Secureness: Limit usage of RAM: optional
--volume /home/$(whoami)/asciidoc3-docker/:/home/ad3docker/:Z \ # Expose the needed configuration files to the container
\ # Z is mandatory only when using SELinux
--user $(id -u) \ # Run container as current user (skip on Windows)
--rm \ # Delete container when exit
--network none \ # Secureness: No network, container is unreachable: optional
asciidoc3/asciidoc3:latest \ # Image to use for the container
Images: latest vs. small
AsciiDoc3 provides two images = latest and small. See the table for the differences. We recommend latest, because small misses some features. Tho only downside is full’s size, but you have to download it only once-in-a-lifetime and it’s about 10s more to wait …
|
|
To run small just replace docker run … asciidoc3/asciidoc3:latest with docker run … asciidoc3/asciidoc3:small |
small |
latest |
remarks |
|
Size |
679 MB, compressed 320 MB |
1,2 GB, compressed 480 MB |
compressed on hub.docker.com |
asciidoc3 command |
✅ |
✅ |
- |
a2x3 command |
✅ |
✅ |
- |
a2x3 -f pdf --fop (or asciidoc3 --pdf=fop) |
✅ |
✅ |
- |
a2x3 -f pdf |
❌ |
✅ |
no dblatex (consumes 350 MB) → use option --fop |
a2x3 -f pdf latexmath |
❌ |
✅ |
no dblatex again → use asciimath |
a2x3 --epubcheck |
❌ |
✅ |
no epubcheck for EPUB output |
a2x3 -f text --lynx |
❌ |
✅ |
no lynx → use default w3m |
validating docbook with jing |
❌ |
✅ |
no jing → default xmllint |
validating docbook with xmlstarlet |
❌ |
✅ |
no xmlstarlet → default xmllint |
Directory Layout
The following layout is recommended. If you install as suggested, this is what you’ll see.
(Host - GNU/Linux or Windows) (AsciiDoc3-container)
-/ c:\ || -/.dockerenv
|- bin |- ... || |- bin
|- dev |- windows32 || |- dev
|- ... |- ... || |- ...
|-home |- Users || |
| | || |
- <username> || |
| || |
- projects || |
... || |
- private || |
... || |
... || |- home
... || | |
- asciidoc3_docker <----mount----> - ad3docker
| || ...
- asciidoc3.conf || ...
- COPYRIGHT || ...
- asciidoc3.py || ...
- a2x3.py || ...
... ||
doc ||
filters ||
conf ||
Dockerfile
AsciiDoc3 Dockerfile latest / full
FROM debian:trixie-slim
LABEL description="asciidoc3/asciidoc3:latest"
LABEL version="4.0.2"
LABEL release-date="2026-05-13"
LABEL maintainer="berthold.gehrke@gmail.com"
# small = latest minus dblatex dvipng epubcheck jing lynx xmlstarlet
RUN apt-get update && \
apt-get install -q -y --no-install-recommends \
vim \
dblatex \
docbook-xml \
docbook-xsl \
docbook-xsl-ns \
docbook5-xml \
dvipng \
epubcheck \
fop \
graphviz \
highlight \
imagemagick \
jing \
liblua5.4-0 \
lilypond \
lynx \
python3 \
python3-lxml \
python3-pygments \
source-highlight \
w3m \
xmlstarlet \
python-is-python3 \
xmlto && \
apt-get clean && \
rm -r /var/cache/apt /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash --no-log-init -u 1235 ad3docker && \
echo 'ad3docker:noPassw0rd!5r' | chpasswd
WORKDIR /home/ad3docker
# install asciidoc3
ADD asciidoc3dockerpodmanimage.tar.gz /home/ad3docker
RUN cp -r /home/ad3docker/AsciiDoc3_docker_files/. /home/ad3docker && \
rm -r /home/ad3docker/AsciiDoc3_docker_files && \
rm -r /home/ad3docker/misc && \
cp -r /home/ad3docker/src/. /home/ad3docker && \
rm -r /home/ad3docker/src/ && \
RUN chmod -R o+w /home/ad3docker && \
chown -R ad3docker:ad3docker /home/ad3docker && \
ln --symbolic /usr/bin/python3 /usr/bin/pycont
USER ad3docker
CMD ["/bin/bash"]
| The ad3docker folder may be empty! |
| This is for debugging … |
|
You are invited to create your own AsciiDoc3-image if you need your individual layout. |
To do so, you may need the tarball we’ve used, see in section download.
Security
Is the AsciiDoc3-container save?
Yes!
-
Container runs as a non-root-user.
-
Container includes no network.
-
Container usage of CPU and RAM is limited.
-
Container writes only in the user’s home-directory.
-
Container can not read any file outside user’s home-directory.