Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asciidoctor/docker-asciidoctor

:ship: A Docker image for using the Asciidoctor toolchain to process AsciiDoc content
https://github.com/asciidoctor/docker-asciidoctor

asciidoctor docker hacktoberfest hacktoberfest2021

Last synced: 3 days ago
JSON representation

:ship: A Docker image for using the Asciidoctor toolchain to process AsciiDoc content

Awesome Lists containing this project

README 

        
:ALPINE_VERSION: 3.20.3

:ASCIIDOCTOR_VERSION: 2.0.23

:ASCIIDOCTOR_CONFLUENCE_VERSION: 0.0.2

:ASCIIDOCTOR_PDF_VERSION: 2.3.19

:ASCIIDOCTOR_DIAGRAM_VERSION: 2.3.1

:ASCIIDOCTOR_EPUB3_VERSION: 2.1.3

:ASCIIDOCTOR_FB2_VERSION: 0.7.0

:ASCIIDOCTOR_MATHEMATICAL_VERSION: 0.3.5

:ASCIIDOCTOR_REVEALJS_VERSION: 5.1.0

:KRAMDOWN_ASCIIDOC_VERSION: 2.1.0

:ASCIIDOCTOR_BIBTEX_VERSION: 0.9.0

:ASCIIDOCTOR_KROKI_VERSION: 0.10.0

:ASCIIDOCTOR_REDUCER_VERSION: 1.0.2

= Asciidoctor Docker Container

:source-highlighter: coderay



////

GitHub renders asciidoctor natively, but DockerHub does not (it needs markdown).

`make README.md` converts this page into markdown.

////



== The environment



This Docker image provides:



* https://asciidoctor.org/[Asciidoctor] {ASCIIDOCTOR_VERSION}

* https://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram] {ASCIIDOCTOR_DIAGRAM_VERSION} with ERD and Graphviz integration (supports plantuml and graphiz diagrams)

* https://asciidoctor.org/docs/asciidoctor-pdf/[Asciidoctor PDF] {ASCIIDOCTOR_PDF_VERSION}

* https://asciidoctor.org/docs/asciidoctor-epub3/[Asciidoctor EPUB3] {ASCIIDOCTOR_EPUB3_VERSION}

* https://github.com/asciidoctor/asciidoctor-fb2/[Asciidoctor FB2] {ASCIIDOCTOR_FB2_VERSION}

* https://github.com/asciidoctor/asciidoctor-mathematical[Asciidoctor Mathematical] {ASCIIDOCTOR_MATHEMATICAL_VERSION}

* https://docs.asciidoctor.org/reveal.js-converter/latest/[Asciidoctor reveal.js] {ASCIIDOCTOR_REVEALJS_VERSION}

* https://rubygems.org/gems/asciimath[AsciiMath]

* Source highlighting using http://rouge.jneen.net[Rouge], https://rubygems.org/gems/coderay[CodeRay] or https://pygments.org/[Pygments]

* https://github.com/asciidoctor/asciidoctor-confluence[Asciidoctor Confluence] {ASCIIDOCTOR_CONFLUENCE_VERSION}

* https://github.com/asciidoctor/asciidoctor-bibtex[Asciidoctor Bibtex] {ASCIIDOCTOR_BIBTEX_VERSION}

* https://github.com/Mogztter/asciidoctor-kroki[Asciidoctor Kroki] {ASCIIDOCTOR_KROKI_VERSION}

* https://github.com/asciidoctor/asciidoctor-reducer[Asciidoctor Reducer] {ASCIIDOCTOR_REDUCER_VERSION}



This image uses Alpine Linux {ALPINE_VERSION} as base image.



NOTE: Docker Engine link:https://docs.docker.com/engine/release-notes/#20100[20.10] or later is required (or any container engine supporting link:https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0[Alpine 3.14]) to avoid unexpected `No such file or directory` errors (such as link:https://github.com/asciidoctor/docker-asciidoctor/issues/214[#214] or link:https://github.com/asciidoctor/docker-asciidoctor/issues/215[#215]).



NOTE: This image uses the Go-based https://github.com/kaishuu0123/erd-go/[erd-go] instead of the original Haskell-based https://github.com/BurntSushi/erd[erd] to allow the Docker image to be provided as a multi-platform image.



== How to use it



Just run:



[source,bash]

----

docker run -it -u $(id -u):$(id -g) -v :/documents/ asciidoctor/docker-asciidoctor

----



or the following for https://podman.io/[Podman]:



[source,bash]

----

podman run -it -v :/documents/ docker.io/asciidoctor/docker-asciidoctor

----



Docker/Podman maps your directory with [path]_/documents_ directory in the container.



NOTE: You might need to add the option `:z` or `:Z` like `:/documents/:z` or `:/documents/:Z` if you are using SELinux. See https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label[Docker docs] or https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options[Podman docs].



After you start the container, you can use Asciidoctor commands to convert AsciiDoc files that you created in the directory mentioned above.

You can find several examples below.



* To run Asciidoctor on a basic AsciiDoc file:

+

[source,bash]

----

asciidoctor sample.adoc

asciidoctor-pdf sample.adoc

asciidoctor-epub3 sample.adoc

----



* To run AsciiDoc on an AsciiDoc file that contains diagrams:

+

[source,bash]

----

asciidoctor -r asciidoctor-diagram sample-with-diagram.adoc

asciidoctor-pdf -r asciidoctor-diagram sample-with-diagram.adoc

asciidoctor-epub3 -r asciidoctor-diagram sample-with-diagram.adoc

----



* To run AsciiDoc on an AsciiDoc file that contains latexmath and stem blocks:

+

[source,bash]

----

asciidoctor -r asciidoctor-mathematical sample-with-diagram.adoc

asciidoctor-pdf -r asciidoctor-mathematical sample-with-diagram.adoc

asciidoctor-epub3 -r asciidoctor-mathematical sample-with-diagram.adoc

----



* To use Asciidoctor Confluence:

+

[source,bash]

----

asciidoctor-confluence --host HOSTNAME --spaceKey SPACEKEY --title TITLE --username USER --password PASSWORD sample.adoc

----



* To use Asciidoctor reveal.js with local downloaded reveal.js:

+

[source,bash]

----

asciidoctor-revealjs sample-slides.adoc

asciidoctor-revealjs -r asciidoctor-diagram sample-slides.adoc

----



* To use Asciidoctor reveal.js with online reveal.js:

+

[source,bash]

----

asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 sample-slides.adoc

asciidoctor-revealjs -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 -r asciidoctor-diagram sample-slides.adoc

----



* To convert files in batch:

+

[source,bash]

----

docker run --rm -u $(id -u):$(id -g) -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc

----

+

or:

+

[source,bash]

----

podman run --rm -v $(pwd):/documents/ docker.io/asciidoctor/docker-asciidoctor asciidoctor-pdf index.adoc

----



== How to contribute / do it yourself?



=== Requirements



You need the following tools:



* A bash compliant command line

* link:http://man7.org/linux/man-pages/man1/make.1.html[GNU make]

* link:https://github.com/sstephenson/bats[Bats] installed and in your bash PATH

* Docker installed and in your path

* link:https://github.com/aquasecurity/trivy[Trivy] cli in case you want to scan images for vulnerabilities



=== How to build and test?



* Bats is used as a test suite runner. Since the ability to build is one way of testing, it is included.



* You just have to run the Bats test suite, from the repository root:

+

[source,bash]

----

make test

----



==== Include test in your build pipeline or test manually



You can use Bats directly to test the image.

Optionally, you can specify a custom image name:



[source,bash]

----

# If you want to use a custom name for the image, OPTIONAL

export DOCKER_IMAGE_NAME_TO_TEST=your-image-name

bats tests/*.bats

----



=== How to scan for vulnerabilities?



* Trivy scans a docker image looking for software versions containing known vulnerabilities (CVEs).

It's always a good idea to scan the image to ensure no new issues are introduced.



* Run the following command to replicate the repo's `CVE Scan` pipeline on an image build locally.

Note the pipeline runs nightly on the latest release version, so it can display issues solved in main branch.

+

[source,bash]

----

trivy image --severity HIGH,CRITICAL asciidoctor:latest

----



==== Deploy



The goal for deploying is to make the Docker image available with the correct Docker tag in Docker Hub.



As a matter of trust and transparency for the end-users, the image is rebuilt by Docker Hub itself by triggering a build.

This only works under the hypothesis of a minimalistic variation between the Docker build in the CI, and the Docker build by Docker Hub.



Deploying the image requires setting the following environment variables: `DOCKERHUB_SOURCE_TOKEN` and `DOCKERHUB_TRIGGER_TOKEN`.

Their values come from a Docker Hub trigger URL: `https://hub.docker.com/api/build/v1/source/${DOCKERHUB_SOURCE_TOKEN}/trigger/${DOCKERHUB_TRIGGER_TOKEN}/call/`.



You might want to set these variables as secret values in your CI to avoid any leaking in the output (as `curl` output for instance).