This tutorial shows you how to build PDFs from markdown and have them online.

We use the test file tests/test.md. It also include formatting examples and which preamble options there are available.

The converted result i shown below.

It is also available as pdf, located here

If you use the docker image from docker-pdf the software is already installed. This is the one we use ourselves, so it should be up-to-date.

Running it localy requires additional software to be installed. See the dockerfile for the latest list.

As of now, the packages needed

apt-get install git pandoc \
        texlive-latex-extra texlive-latex-recommended texlive-latex-base \
        linkchecker poppler-utils

In order to use it, download the latest version of both the scripts and the UCL template.

E.g.

wget -O ucl_template-latest.tgz https://moozer.gitlab.io/document_templates/ucl_template-latest.tgz
mkdir -p template
tar xzvf ucl_template-latest.tgz -C template

wget -O doc_scripts-latest.tgz https://moozer.gitlab.io/document_templates/doc_scripts-latest.tgz
mkdir -p template/scripts
tar xzvf doc_scripts-latest.tgz -C template/scripts

They are other versionse available from the releases page.

Note: This replaces the previous method of using submodules. That method still works, but is considered obsolete.

To convert the file mydoc.md, use

template/scripts/build_pdf.sh mydoc
template/scripts/test_pdf.sh mydoc

This will create mydoc.pdf and run the predefined tests. The test is currently linkchecking, which is disabled on some systems due to upstream bugs.

The main idea of this project was to create PDFs automatically when .md files were updated, so that is a possibility.

In order to do this on gitlab, you need to edit the .gitlab-ci.yml for project and add something like the following to generate pdfs from all .md files in /docs

build_pdfs_custom:
  image: registry.gitlab.com/moozer/docker-pdf/buster:latest
  before_script:
    - wget -O ucl_template-latest.tgz https://moozer.gitlab.io/document_templates/ucl_template-latest.tgz
    - mkdir -p template
    - tar xzvf ucl_template-latest.tgz -C template

    - wget -O doc_scripts-latest.tgz https://moozer.gitlab.io/document_templates/doc_scripts-latest.tgz
    - mkdir -p template/scripts
    - tar xzvf doc_scripts-latest.tgz -C template/scripts
  script:
    - for F in $(ls *.md); do
        template/scripts/build_pdf.sh $(basename -s .md $F);
        template/scripts/test_pdf.sh $(basename -s .md $F);
      done
  artifacts:
    paths:
      - *.pdf

This will convert all .md files in docs to .pdf, and store them as artifacts for jobs to come.

We have a latest versions located at ucl_template-latest.tgz and doc_scripts-latest.tgz. These are the rememded version to use, since you will get any updates made to the template.

For the list of releases and their URLs go here