diff --git a/.dockerignore b/.dockerignore index 0b7af8b5..1646f367 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,6 @@ tests .git* +README-original.adoc README.adoc README.md cache diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ad01ff22..e9db1bc2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,10 +27,10 @@ jobs: run: | make build make test - make README.md + make README - name: Deploy if: github.event_name != 'pull_request' - run: make deploy-README.md deploy + run: make deploy-README deploy env: DOCKERHUB_SOURCE_TOKEN: ${{ secrets.DOCKERHUB_SOURCE_TOKEN }} DOCKERHUB_TRIGGER_TOKEN: ${{ secrets.DOCKERHUB_TRIGGER_TOKEN }} diff --git a/Makefile b/Makefile index 303dc5be..5af422b5 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ export TESTS_ENV_FILE PANDOC_VERSION ?= 2.10.1 -all: build test README.md +all: build test README build: docker build \ @@ -79,13 +79,15 @@ cache/pandoc-$(PANDOC_VERSION)/bin/pandoc: cache/pandoc-$(PANDOC_VERSION)-linux. tar xzf "$(CURDIR)/cache/pandoc-$(PANDOC_VERSION)-linux.tar.gz" -C "$(CURDIR)/cache" # GitHub renders asciidoctor but DockerHub requires markdown. -# This recipe creates README.md from README.adoc. -README.md: build cache/pandoc-$(PANDOC_VERSION)/bin/pandoc +# This recipe creates README.md and README.adoc from README-original.adoc and env_vars.yml. +README: build cache/pandoc-$(PANDOC_VERSION)/bin/pandoc + cat tests/env_vars.yml | sed -e 's/^[A-Z]/:&/' | sed '/^#/d' > "$(CURDIR)/cache/env_vars.adoc" + cat "$(CURDIR)/cache/env_vars.adoc" README-original.adoc > README.adoc docker run --rm -t -v $(CURDIR):/documents --entrypoint bash $(DOCKER_IMAGE_NAME_TO_TEST) \ -c "asciidoctor -b docbook -a leveloffset=+1 -o - README.adoc | /documents/cache/pandoc-$(PANDOC_VERSION)/bin/pandoc --atx-headers --wrap=preserve -t gfm -f docbook - > README.md" -deploy-README.md: README.md - git add README.md && git commit -s -m "Updating README.md using 'make README.md command'" \ - && git push origin $(shell git rev-parse --abbrev-ref HEAD) || echo 'No changes to README.md' +deploy-README: README + git add README.adoc README.md && git commit -s -m "Updating README files using 'make README command'" \ + && git push origin $(shell git rev-parse --abbrev-ref HEAD) || echo 'No changes to README files' -.PHONY: all build test shell deploy clean README.md deploy-README.md +.PHONY: all build test shell deploy clean README deploy-README diff --git a/README-original.adoc b/README-original.adoc new file mode 100644 index 00000000..c97f7b6a --- /dev/null +++ b/README-original.adoc @@ -0,0 +1,133 @@ += 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} + +This image uses Alpine Linux 3.13 as base image. + +== How to use it + +Just run: + +[source,bash] +---- +docker run -it -v :/documents/ asciidoctor/docker-asciidoctor +---- + +Docker maps your directory with [path]_/documents_ directory in the container. + +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 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 -v $(pwd):/documents/ 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 + +=== 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 +---- + +==== 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). diff --git a/README.adoc b/README.adoc index 5c4f8a58..5a695958 100644 --- a/README.adoc +++ b/README.adoc @@ -1,3 +1,13 @@ +:ASCIIDOCTOR_VERSION: 2.0.15 +:ASCIIDOCTOR_CONFLUENCE_VERSION: 0.0.2 +:ASCIIDOCTOR_PDF_VERSION: 1.5.4 +:ASCIIDOCTOR_DIAGRAM_VERSION: 2.1.2 +:ASCIIDOCTOR_EPUB3_VERSION: 1.5.1 +:ASCIIDOCTOR_FB2_VERSION: 0.5.1 +:ASCIIDOCTOR_MATHEMATICAL_VERSION: 0.3.5 +:ASCIIDOCTOR_REVEALJS_VERSION: 4.1.0 +:KRAMDOWN_ASCIIDOC_VERSION: 1.0.1 +:ASCIIDOCTOR_BIBTEX_VERSION: 0.8.0 = Asciidoctor Docker Container :source-highlighter: coderay @@ -10,17 +20,17 @@ GitHub renders asciidoctor natively, but DockerHub does not (it needs markdown). This Docker image provides: -* https://asciidoctor.org/[Asciidoctor] 2.0.12 -* https://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram] 2.1.0 with ERD and Graphviz integration (supports plantuml and graphiz diagrams) -* https://asciidoctor.org/docs/asciidoctor-pdf/[Asciidoctor PDF] 1.5.4 -* https://asciidoctor.org/docs/asciidoctor-epub3/[Asciidoctor EPUB3] 1.5.0.alpha.19 -* https://github.com/asciidoctor/asciidoctor-fb2/[Asciidoctor FB2] 0.5.1 -* https://github.com/asciidoctor/asciidoctor-mathematical[Asciidoctor Mathematical] 0.3.5 -* https://docs.asciidoctor.org/reveal.js-converter/latest/[Asciidoctor reveal.js] 4.1.0 +* 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] 0.0.2 -* https://github.com/asciidoctor/asciidoctor-bibtex[Asciidoctor Bibtex] 0.8.0 +* https://github.com/asciidoctor/asciidoctor-confluence[Asciidoctor Confluence] {ASCIIDOCTOR_CONFLUENCE_VERSION} +* https://github.com/asciidoctor/asciidoctor-bibtex[Asciidoctor Bibtex] {ASCIIDOCTOR_BIBTEX_VERSION} This image uses Alpine Linux 3.13 as base image. diff --git a/README.md b/README.md index 34b1aee8..20633d3d 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ This Docker image provides: -- [Asciidoctor](https://asciidoctor.org/) 2.0.12 +- [Asciidoctor](https://asciidoctor.org/) 2.0.15 -- [Asciidoctor Diagram](https://asciidoctor.org/docs/asciidoctor-diagram/) 2.1.0 with ERD and Graphviz integration (supports plantuml and graphiz diagrams) +- [Asciidoctor Diagram](https://asciidoctor.org/docs/asciidoctor-diagram/) 2.1.2 with ERD and Graphviz integration (supports plantuml and graphiz diagrams) - [Asciidoctor PDF](https://asciidoctor.org/docs/asciidoctor-pdf/) 1.5.4 -- [Asciidoctor EPUB3](https://asciidoctor.org/docs/asciidoctor-epub3/) 1.5.0.alpha.19 +- [Asciidoctor EPUB3](https://asciidoctor.org/docs/asciidoctor-epub3/) 1.5.1 - [Asciidoctor FB2](https://github.com/asciidoctor/asciidoctor-fb2/) 0.5.1