GitLab Pandoc Continuous Integration

Updated 10012022-171438

Using pandoc with GitLab CI/CD

pipeline
pipeline

You can use pandoc, the universal markup converter, with GitLab CI/CD to convert documents.

GitLab CI/CD is an Infrastructure as a Service (IaaS) from GitLab, that allows you to automatically run code on GitLab's servers on every push. For example, you can use GitLab CI/CD to convert some file.md to file.pdf (via LaTeX) and upload the results to a web host.

All examples can be found in the .gitlab-ci.yml.

Using pandoc's Docker Images

You can directly use use docker container in GitLab CI/CD's jobs.

If you need LaTeX (because you want to convert through to PDF), you should use the pandoc/latex image. Otherwise, the smaller pandoc/core will suffice.

It is a good idea to be explicit about the pandoc version you require, such as pandoc/core:2.9. This way, any future breaking changes in pandoc will not affect your job. You can find out whatever the latest released docker image is on docker hub You should avoid specifying no tag or the latest tag -- these will float to the latest image and will expose your job to potentially breaking changes.

Simple Usage

You have to change the entrypoint of the docker image to be able to use them within the GitLab CI/CD job.

Below is a complete example to run pandoc --help:

simple:
  image:
    name: pandoc
    entrypoint: ["/bin/sh", "-c"]
  script:
    pandoc --help

Advanced Usage

GitLab CI/CD is more or less calling shell commands, so you can work pretty similar to regular shell scripts. As long as it does not conflict with the yaml syntax.

The next Job builds multiple .md file to a single .pdf using LaTeX and uploads the resulting file to GitLab as an Job artifact, which can quickly be downloaded from GitLab:

advanced:
  image:
    name: pandoc/latex
    entrypoint: ["/bin/sh", "-c"]
  script:
    - echo "Lorem ipsum" > lorem_1.md  # create two example files
    - echo "dolor sit amet" > lorem_2.md
    - mkdir output  # create output dir
    - pandoc --output=output/result.pdf *.md
  artifacts:
    paths:
      - output