{"id":14036657,"url":"https://github.com/pandoc/pandoc-action-example","last_synced_at":"2025-12-29T23:05:08.907Z","repository":{"id":49874689,"uuid":"202176953","full_name":"pandoc/pandoc-action-example","owner":"pandoc","description":"using the pandoc document converter on GitHub Actions","archived":false,"fork":false,"pushed_at":"2025-03-01T12:38:26.000Z","size":37,"stargazers_count":373,"open_issues_count":9,"forks_count":85,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-01T13:33:22.857Z","etag":null,"topics":["continuous-delivery","continuous-integration","github-actions","html","latex","markdown","pandoc"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pandoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-13T15:49:05.000Z","updated_at":"2025-03-01T12:38:31.000Z","dependencies_parsed_at":"2024-12-02T15:35:25.033Z","dependency_job_id":"fb9d1fb9-b15e-4ba2-b1fc-12b09dfb996f","html_url":"https://github.com/pandoc/pandoc-action-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pandoc/pandoc-action-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc%2Fpandoc-action-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc%2Fpandoc-action-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc%2Fpandoc-action-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc%2Fpandoc-action-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pandoc","download_url":"https://codeload.github.com/pandoc/pandoc-action-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc%2Fpandoc-action-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267294180,"owners_count":24065343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-delivery","continuous-integration","github-actions","html","latex","markdown","pandoc"],"created_at":"2024-08-12T03:02:07.692Z","updated_at":"2025-12-29T23:05:08.862Z","avatar_url":"https://github.com/pandoc.png","language":null,"funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"# Using `pandoc` with [GitHub Actions](https://github.com/features/actions)\n\n\u003c!-- badges: start --\u003e\n[![Simple Usage](https://github.com/maxheld83/pandoc-example/workflows/Simple%20Usage/badge.svg)](https://github.com/maxheld83/pandoc-example/actions)\n[![Long Usage](https://github.com/maxheld83/pandoc-example/workflows/Long%20Usage/badge.svg)](https://github.com/maxheld83/pandoc-example/actions)\n[![Advanced Usage](https://github.com/maxheld83/pandoc-example/workflows/Advanced%20Usage/badge.svg)](https://github.com/maxheld83/pandoc-example/actions)\n\u003c!-- badges: end --\u003e\n\nYou can use [pandoc](https://pandoc.org/), the **universal markup converter**, on GitHub Actions to convert documents.\n\nGitHub 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).\nFor example, you can use GitHub Actions to convert some `file.md` to `file.pdf` (via LaTeX) and upload the results to a web host.\n\n\n## Using `docker://pandoc` Images Directly\n\nYou can now *directly* [reference container actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/configuring-a-workflow#referencing-a-container-on-docker-hub) on GitHub Actions.\nYou do not *need* a separate GitHub Action.\n\nIf you need LaTeX (because you want to convert through to PDF), you should use the `docker://pandoc/latex` image.\nOtherwise, the smaller `docker://pandoc/core` will suffice.\n\nIt is a good idea to be explicit about the pandoc version you require, such as `docker://pandoc/core:3.5`.\nThis way, any future breaking changes in pandoc will not affect your workflow.\nYou can find out whatever the latest released docker image is on [docker hub](https://hub.docker.com/r/pandoc/core/tags).\nYou 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.\n\n\n## Simple Usage\n\nYou can use pandoc inside GitHub actions exactly as you would use it on the command line.\nThe string passed to `args` gets appended to the [`pandoc` command](https://pandoc.org/MANUAL.html).\n\nThe below example is equivalent to running `pandoc --help`.\n\nYou can see it in action [here](https://github.com/pandoc/pandoc-action-example).\n\n```yaml\nname: Simple Usage\n\non: push\n\njobs:\n  convert_via_pandoc:\n    runs-on: ubuntu-22.04\n    steps:\n      - uses: docker://pandoc/core:3.5\n        with:\n          args: \"--help\" # gets appended to pandoc command\n```\n\n\n## Long Pandoc Calls\n\nRemember that as per the [GitHub Actions workflow syntax](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs), \"an `array of strings` is not supported by the `jobs.\u003cjob_id\u003e.steps.with.args` parameter.\nPandoc commands can sometimes get quite long and unwieldy, but you must pass them as a *single* string.\nIf you want to break up the string over several lines, you can use YAML's [block chomping indicator](https://yaml.org/spec/1.2.2/#8112-block-chomping-indicator):\n\n```yaml\nname: Long Usage\n\non: push\n\njobs:\n  convert_via_pandoc:\n    runs-on: ubuntu-22.04\n    steps:\n      - run: echo \"foo\" \u003e input.txt  # create an example file\n      - uses: docker://pandoc/core:3.5\n        with:\n          args: \u003e-  # allows you to break string into multiple lines\n            --standalone\n            --output=index.html\n            input.txt\n```\n\nYou can see it in action [here](https://github.com/pandoc/pandoc-action-example).\n\n\n## Advanced Usage\n\nYou can also:\n\n- create an output directory to compile into; makes it easier to deploy outputs.\n- upload the output directory to [GitHub's artifact storage](https://help.github.com/en/articles/managing-a-workflow-run#downloading-logs-and-artifacts); you can quickly download the results from your GitHub Actions tab in your repo.\n\nRemember that wildcard substitution (say, `pandoc *.md`) or other shell features frequently used with pandoc do not work inside GitHub Actions yaml files `args:` fields.\nOnly [GitHub Actions context and expression syntax](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions) can be used here.\nIf you want to make use of such shell features, you have to run that in a separate step in a `run` field and store the result in the GitHub actions context.\nThe below workflow includes an example of how to do this to concatenate several input files.\n\nYou can see it in action (haha!) [here](https://github.com/pandoc/pandoc-action-example).\n\n```yaml\nname: Advanced Usage\n\non: push\n\njobs:\n  convert_via_pandoc:\n    runs-on: ubuntu-22.04\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: create file list\n        id: files_list\n        run: |\n          echo \"Lorem ipsum\" \u003e lorem_1.md  # create two example files\n          echo \"dolor sit amet\" \u003e lorem_2.md\n          mkdir output  # create output dir\n          # this will also include README.md\n          echo \"files=$(printf '\"%s\" ' *.md)\" \u003e $GITHUB_OUTPUT\n\n      - uses: docker://pandoc/latex:3.5\n        with:\n          args: --output=output/result.pdf ${{ steps.files_list.outputs.files }}\n          \n      - uses: actions/upload-artifact@v4\n        with:\n          name: output\n          path: output\n```\n\n## pandoc-extra and Github Actions\n\nBecause Github Actions rewrites the value of `$HOME` in runners the template directory cannot be found leading to errors such as:\n\n```\nCould not find data file templates/eisvogel.latex\n```\n\nA work around to this is to specify the exact location on the filesystem of the template:\n\n```\n- uses: docker://pandoc/extra:3.5\n        with:\n          args: content/cv.md --output=content/cv.pdf --template /.pandoc/templates/eisvogel.latex --listings -V block-headings\n```\n\n## Alternatives\n\nIf you need to have Pandoc installed and available globally, for example because it is being used in a subprocess by a library or application, you can use one of the two following alternative actions:\n\n- [pandoc/actions/setup](https://github.com/pandoc/actions/tree/main/setup) (Linux and MacOS runners support)\n- [r-lib/setup-pandoc](https://github.com/r-lib/actions/tree/v2-branch/setup-pandoc) (Linux, MacOS and Windows runners support)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandoc%2Fpandoc-action-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpandoc%2Fpandoc-action-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandoc%2Fpandoc-action-example/lists"}