Skip to content
using the pandoc document converter on GitHub Actions
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows use folding style Dec 21, 2019
README.md use proper description of pandoc Dec 21, 2019

README.md

Using pandoc with GitHub Actions

Simple Usage Long Usage Advanced Usage

You can use pandoc, the universal markup converter, on GitHub Actions to convert documents.

GitHub Actions is an Infrastructure as a Service (IaaS) from GitHub, that allows you to automatically run code on GitHub's servers on every push (or a bunch of other GitHub events). For example, you can use GitHub Actions to convert some file.md to file.pdf (via LaTeX) and upload the results to a web host.

Using docker://pandoc Images Directly

You can now directly reference container actions on GitHub Actions. You do not need a separate GitHub Action.

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

It is a good idea to be explicit about the pandoc version you require, such as docker://pandoc/core:2.9. This way, any future breaking changes in pandoc will not affect your workflow. 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 workflow to potentially breaking changes.

Simple Usage

You can use pandoc inside GitHub actions exactly as you would use it on the command line. The string passed to args gets appended to the pandoc command.

The below example is equivalent to running pandoc --help.

You can see it in action here.

name: Simple Usage

on: push

jobs:
  convert_via_pandoc:
    runs-on: ubuntu-18.04
    steps:
      - uses: docker://pandoc/core:2.9
        with:
          args: "--help" # gets appended to pandoc command

Long Pandoc Calls

Remember that as per the GitHub Actions workflow syntax, "an array of strings is not supported by the jobs.<job_id>.steps.with.args parameter. Pandoc commands can sometimes get quite long and unwieldy, but you must pass them as a single string. If you want to break up the string over several lines, you can use YAML's block chomping indicator:

name: Long Usage

on: push

jobs:
  convert_via_pandoc:
    runs-on: ubuntu-18.04
    steps:
      - run: echo "foo" > input.txt  # create an example file
      - uses: docker://pandoc/core:2.9
        with:
          args: |>  # allows you to break string into multiple lines
            --standalone
            --output=index.html
            input.txt

You can see it in action here.

Advanced Usage

You can also:

  • create an output directory to compile into; makes it easier to deploy outputs.
  • upload the output directory to GitHub's artifact storage; you can quickly download the results from your GitHub Actions tab in your repo.

You can see it in action (haha!) here.

name: Advanced Usage

on: push

jobs:
  convert_via_pandoc:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
      - run: mkdir output
      - uses: docker://pandoc/latex:2.9
        with: # needs a README in your repo root!
          args: "--standalone --output=output/README.pdf README.md"
      - uses: actions/upload-artifact@master
        with:
          name: output
          path: output
You can’t perform that action at this time.