Merge branch 'feature/docker' into main

Closes #97.

.github/workflows/main.yml

@@ -1,4 +1,4 @@
-name: Test
+name: Test and publish
 on:
   push:
   pull_request:
@@ -15,51 +15,17 @@ jobs:
       - name: Run ShellCheck
         uses: ludeeus/action-shellcheck@master
   test:
-    name: Test
+    name: Test and publish
     runs-on: ubuntu-latest
-    container:
-      image: texlive/texlive:latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
-      - name: Install additional packages
-        run: |
-          set -ex
-          apt-get -qy update
-          apt-get -qy install curl gawk graphviz m4 pandoc parallel python3-pygments ruby wget
-      - name: Generate the ConTeXt file database
-        run: |
-          set -ex
-          mtxrun --generate
-      - name: Install the Markdown package
-        run: |
-          set -ex
-          make base
-          mkdir -p                                     ~/texmf/tex/luatex/markdown/
-          cp -f markdown.lua                           ~/texmf/tex/luatex/markdown/
-          mkdir -p                                     ~/texmf/scripts/markdown/
-          cp -f markdown-cli.lua                       ~/texmf/scripts/markdown/
-          mkdir -p                                     ~/texmf/tex/generic/markdown/
-          cp -f markdown.tex                           ~/texmf/tex/generic/markdown/
-          mkdir -p                                     ~/texmf/tex/latex/markdown/
-          cp -f markdown.sty                           ~/texmf/tex/latex/markdown/
-          cp -f markdownthemewitiko_dot.sty            ~/texmf/tex/latex/markdown/
-          cp -f markdownthemewitiko_graphicx_http.sty  ~/texmf/tex/latex/markdown/
-          cp -f markdownthemewitiko_tilde.sty          ~/texmf/tex/latex/markdown/
-          mkdir -p                                     ~/texmf/tex/context/third/markdown/
-          cp -f t-markdown.tex                         ~/texmf/tex/context/third/markdown/
-      - name: Typeset documentation and example documents
-        run: |
-          set -ex
-          make -j `nproc` all
+      - name: Build Docker image
+        run: make docker-image
       - name: Run tests
-        run: |
-          set -ex
-          make test
+        run: docker run -v "$PWD":/git-repo -w /git-repo witiko/markdown make test
       - name: Build distribution archives
-        run: |
-          set -ex
-          make dist
+        run: docker run -v "$PWD":/git-repo -w /git-repo witiko/markdown make dist
       - name: Upload artifact markdown.tds.zip
         uses: actions/upload-artifact@v2
         with:
@@ -80,3 +46,25 @@ jobs:
         with:
           name: markdown.pdf
           path: markdown.pdf
+      - name: Create a prerelease
+        if: github.ref == 'refs/heads/main'
+        uses: marvinpinto/action-automatic-releases@latest
+        with:
+          title: The latest version
+          automatic_release_tag: latest
+          prerelease: true
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          files: |
+            markdown.tds.zip
+            markdown.ctan.zip
+            markdown.zip
+            markdown.pdf
+      - name: Authenticate registry
+        if: github.ref == 'refs/heads/main'
+        uses: azure/docker-login@v1
+        with:
+          username: ${{ secrets.DOCKER_HUB_USER }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+      - name: Publish Docker image
+        if: github.ref == 'refs/heads/main'
+        run: docker push witiko/markdown --all-tags

Dockerfile

@@ -0,0 +1,79 @@
+ARG AUXILIARY_FILES="\
+    /tmp/* \
+    /var/tmp/* \
+    /var/log/* \
+    /var/lib/apt/lists/* \
+    /var/lib/{apt,dpkg,cache,log}/* \
+    /usr/share/man/* \
+    /usr/share/locale/* \
+    /var/cache/apt/* \
+"
+ARG DEPENDENCIES="\
+    curl \
+    gawk \
+    graphviz \
+    m4 \
+    pandoc \
+    parallel \
+    python3-pygments \
+    ruby \
+    wget \
+    zip \
+"
+ARG BUILD_DIR=/git-repo
+ARG DIST_DIR=${BUILD_DIR}/dist
+ARG INSTALL_DIR=/usr/local/texlive/texmf-local
+
+FROM texlive/texlive:latest as build
+ARG DEPENDENCIES
+ARG BUILD_DIR
+ARG DIST_DIR
+ARG INSTALL_DIR
+ENV DEBIAN_FRONTEND=noninteractive \
+    TERM=xterm
+COPY . /git-repo/
+RUN set -o errexit \
+ && set -o nounset \
+ && set -o xtrace \
+ && apt-get -qy update \
+ && apt-get -qy install --no-install-recommends ${DEPENDENCIES} \
+ && mtxrun --generate \
+ && make -C ${BUILD_DIR} base \
+ && mkdir -p                                                  ${INSTALL_DIR}/tex/luatex/markdown/ \
+ && cp -f ${BUILD_DIR}/markdown.lua                           ${INSTALL_DIR}/tex/luatex/markdown/ \
+ && mkdir -p                                                  ${INSTALL_DIR}/scripts/markdown/ \
+ && cp -f ${BUILD_DIR}/markdown-cli.lua                       ${INSTALL_DIR}/scripts/markdown/ \
+ && mkdir -p                                                  ${INSTALL_DIR}/tex/generic/markdown/ \
+ && cp -f ${BUILD_DIR}/markdown.tex                           ${INSTALL_DIR}/tex/generic/markdown/ \
+ && mkdir -p                                                  ${INSTALL_DIR}/tex/latex/markdown/ \
+ && cp -f ${BUILD_DIR}/markdown.sty                           ${INSTALL_DIR}/tex/latex/markdown/ \
+ && cp -f ${BUILD_DIR}/markdownthemewitiko_dot.sty            ${INSTALL_DIR}/tex/latex/markdown/ \
+ && cp -f ${BUILD_DIR}/markdownthemewitiko_graphicx_http.sty  ${INSTALL_DIR}/tex/latex/markdown/ \
+ && cp -f ${BUILD_DIR}/markdownthemewitiko_tilde.sty          ${INSTALL_DIR}/tex/latex/markdown/ \
+ && mkdir -p                                                  ${INSTALL_DIR}/tex/context/third/markdown/ \
+ && cp -f ${BUILD_DIR}/t-markdown.tex                         ${INSTALL_DIR}/tex/context/third/markdown/ \
+ && texhash \
+ && make -C ${BUILD_DIR} dist \
+ && mkdir ${DIST_DIR} \
+ && unzip ${BUILD_DIR}/markdown.tds.zip -d ${DIST_DIR}
+
+FROM texlive/texlive:latest
+ARG AUXILIARY_FILES
+ARG DEPENDENCIES
+ARG DIST_DIR
+ARG INSTALL_DIR
+LABEL authors="Vít Novotný <witiko@mail.muni.cz>"
+ENV DEBIAN_FRONTEND=noninteractive \
+    TERM=xterm
+COPY --from=build ${DIST_DIR} ${INSTALL_DIR}/
+RUN set -o errexit \
+ && set -o nounset \
+ && set -o xtrace \
+ && apt-get -qy update \
+ && apt-get -qy install --no-install-recommends ${DEPENDENCIES} \
+ && apt-get -qy autoclean \
+ && apt-get -qy clean \
+ && apt-get -qy autoremove --purge \
+ && rm -rf ${AUXILIARY_FILES} \
+ && mtxrun --generate \
+ && texhash

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all base clean implode dist test examples
+.PHONY: all base clean implode dist test examples docker-image
 AUXFILES=markdown.bbl markdown.cb markdown.cb2 markdown.glo markdown.bbl \
   markdown.run.xml markdown.bib markdown.markdown.in markdown.markdown.lua \
   markdown.markdown.out markdown-interfaces.md markdown-miscellanea.md \
@@ -45,6 +45,11 @@ all: $(MAKEABLES)
 base: $(INSTALLABLES)
 	$(MAKE) clean
 
+# This target builds a witiko/markdown Docker image.
+docker-image:
+	docker build -t witiko/markdown:latest .
+	docker tag witiko/markdown:latest witiko/markdown:$(shell git describe --tags --always --long)
+
 # This target extracts the source files out of the DTX archive.
 $(INSTALLABLES) $(MARKDOWN_USER_MANUAL): $(INSTALLER) $(DTXARCHIVE)
 	xetex $<

README.md

@@ -2,7 +2,7 @@ Markdown
 ========
 
 [![release](https://img.shields.io/github/release/witiko/markdown.svg)][release]
-[![ci](https://github.com/Witiko/markdown/workflows/Test/badge.svg)][ci]
+[![ci](https://github.com/witiko/markdown/actions/workflows/main.yml/badge.svg)][ci]
 
  [release]:  https://github.com/Witiko/markdown/releases/latest  "Releases · Witiko/markdown"
  [ci]:       https://github.com/Witiko/markdown/actions          "GitHub Actions"
@@ -17,8 +17,95 @@ is encouraged. 😉
 
  [markdown]: https://daringfireball.net/projects/markdown/basics  "Daring Fireball: Markdown Basics"
 
+Using Markdown
+--------------
+
+For a quick introduction to the Markdown package, you can use
+[our official Docker image][docker-witiko/markdown].
+
+### Typesetting a Document
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+
+``` latex
+\documentclass{book}
+\usepackage{markdown}
+\markdownSetup{pipeTables,tableCaptions}
+\begin{document}
+\begin{markdown}
+Introduction
+============
+## Section
+### Subsection
+Hello *Markdown*!
+
+| Right | Left | Default | Center |
+|------:|:-----|---------|:------:|
+|   12  |  12  |    12   |    12  |
+|  123  |  123 |   123   |   123  |
+|    1  |    1 |     1   |     1  |
+
+: Table
+\end{markdown}
+\end{document}
+```
+
+Next, run LuaLaTeX from [our official Docker image][docker-witiko/markdown]:
+
+```
+$ docker run --rm -v "$PWD":/workdir -w /workdir witiko/markdown latexmk -lualatex document.tex
+```
+
+A PDF document named `document.pdf` should be produced and contain the
+following output:
+
  ![banner](banner.png "An example LaTeX document using the Markdown package")
 
+Congratulations, You just typeset your first Markdown document!
+
+### Continuous Integration
+
+If you need the latest features of the Markdown package in your continuous
+integration pipelines, you can use
+[our official Docker image][docker-witiko/markdown] as a drop-in replacement
+for [the `texlive/texlive:latest` Docker image][docker-texlive/texlive].
+
+The following example shows a [GitHub Actions][github-actions] workflow. If you
+create a Github repository with a text document named `document.tex`, this
+workflow will automatically typeset and prerelease a PDF document named
+`document.pdf` using the latest development version of the Markdown package:
+
+``` yaml
+name: Typeset and prerelease the book
+on:
+  push:
+jobs:
+  typeset:
+    runs-on: ubuntu-latest
+    container:
+      image: witiko/markdown:latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: latexmk -lualatex document.tex
+      - uses: marvinpinto/action-automatic-releases@latest
+        with:
+          title: The latest typeset book
+          automatic_release_tag: latest
+          prerelease: true
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          files: document.pdf
+```
+
+In fact, this is how we automatically produce
+[the latest documentation][latest-release] for the Markdown package.
+
+ [docker-witiko/markdown]: https://hub.docker.com/r/witiko/markdown  "witiko/markdown - Docker Image"
+ [docker-texlive/texlive]: https://hub.docker.com/r/texlive/texlive  "texlive/texlive - Docker Image"
+
+ [github-actions]: https://docs.github.com/actions  "GitHub Actions Documentation"
+ [latest-release]: https://github.com/witiko/markdown/releases/tag/latest
+
 Further information
 -------------------
 
@@ -103,7 +190,7 @@ Contributing
 ------------
 
 Apart from the example markdown documents, tests, and continuous integration,
-which are placed in the `examples/`, `tests/`, and `.circleci/` directories,
+which are placed in the `examples/`, `tests/`, and `.github/` directories,
 the complete source code and documentation of the package are placed in the
 `markdown.dtx` document following the [literate programming][] paradigm.
 Some useful commands, such as building the release archives and typesetting
@@ -124,6 +211,12 @@ documentation is placed inside TeX comments and marked up using the
 [ltxdockit][] LaTeX document class. Support for typesetting the documentation
 is provided by the [doc][] LaTeX package.
 
+To facilitate continuous integration and sharing of the Markdown package,
+there exists an [official Docker image][docker-witiko/markdown], which can be
+reproduced by running the `docker build` command on `Dockerfile` (`docker build
+-t witiko/markdown .`). The `make docker-image` command is provided by
+`Makefile` for convenience.
+
  [doc]:                  https://ctan.org/pkg/doc                           "doc – Format LaTeX documentation"
  [DocStrip]:             https://ctan.org/pkg/docstrip                      "docstrip – Remove comments from file"
  [LaTeXMK]:              https://ctan.org/pkg/latexmk                       "latexmk – Fully automated LaTeX document generation"