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: small (= default = latest) and full.
Learn more.
So, start the AsciiDoc3 docker experience right now! Follow the steps described below.
|
The AsciiDoc3 container comes in two tagged images: latest and full. See here for the differences. If you prefer the full image, replace latest with full when running through the following steps . |
Quickstart
You want to start in a few seconds? Take a look at this quickstart. More details are given below.
Quickstart GNU/Linux
(install docker)
mkdir /home/$(whoami)/asciidoc3_docker
cd /home/$(whoami)/asciidoc3_docker
wget https://asciidoc3.org/download/AsciiDoc3_docker_environment.tar.gz tar -xzf AsciiDoc3_docker_environment.tar.gz -C ~/asciidoc3_docker --strip-components=1 rm AsciiDoc3_docker_environment.tar.gz && rm -r AsciiDoc3_docker_environment 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. |
 | This is an oneliner. |
Allow about 30s 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 name instead of asciidoc3_docker. |
Now we have to open PowerShell as Admin since we have to download a file and add some symlinks:
(admin rights) cd C:\Users\<username>\asciidoc3_docker
| Replace <username> with your username. |
| Or download here: Download Container (Docker/Podman) |
If you use - as recommended - a tool like 7-zip (Windows 10) or the built-in archive tool as admin for Windows 11 the symlinks are generated.
If you download the zip - unzip doesn’t handle symlinks - or the symlinks are missing for whatever reason add the symlinks in the Admin’s PowerShell.
(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
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:
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 (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, WSL2 is recommended.
A non-admin user needs permission to start a container: search the web for somthing like windows 10 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.
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 $@; }
| This is 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 here.
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! |
WSL2 or Hyper-V
AsciiDoc3-docker works both with WSL2 and Hyper-V. WSL2 seems to be more robust and is recommended by MicroSoft®. Docker also says, WSL2 provides better performance than the legacy Hyper-V backend.
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 }
| This is 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 here.
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 since image latest has 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. full
AsciiDoc3 provides two images = latest and full. See the table for the differences. We recommend full - latest misses some features. Tho only downside is full’s size, but you have to download it only once-in-a-lifetime …
|
|
To run full just replace docker run … asciidoc3/asciidoc3:latest with docker run … asciidoc3/asciidoc3:full |
AsciiDoc3 images: latest vs. full
latest |
full |
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 |
✅ |
✅ |
- |
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/suggested.
(Host - your system -, 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 ubuntu:24.04
LABEL description="asciidoc3/asciidoc3:latest"
LABEL version="4.0.1"
LABEL release-date="2025-03-07"
LABEL maintainer="berthold.gehrke@gmail.com"
# You may ignore the following message during package install:
# https://stackoverflow.com/questions/53493146/ \
# debconf-delaying-package-configuration-since-apt-utils-is-not-installed
# full = latest plus dblatex dvipng epubcheck jing lynx xmlstarlet
RUN apt-get update && \
apt-get install -q -y --no-install-recommends \
# 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 \
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 AsciiDoc3_docker_files.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/ && \
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. |
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.
