{"id":13475295,"url":"https://github.com/xu-cheng/latex-action","last_synced_at":"2025-05-15T05:07:16.917Z","repository":{"id":39589485,"uuid":"203533074","full_name":"xu-cheng/latex-action","owner":"xu-cheng","description":":octocat: GitHub Action to compile LaTeX documents","archived":false,"fork":false,"pushed_at":"2025-04-13T02:04:44.000Z","size":126,"stargazers_count":1212,"open_issues_count":3,"forks_count":140,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-27T09:35:07.341Z","etag":null,"topics":["github-actions","latex"],"latest_commit_sha":null,"homepage":"https://github.com/xu-cheng/latex-action","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xu-cheng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":["xu-cheng"]}},"created_at":"2019-08-21T07:43:22.000Z","updated_at":"2025-04-25T02:02:46.000Z","dependencies_parsed_at":"2024-01-09T13:10:31.226Z","dependency_job_id":"07879a65-11e1-4c3d-b3f0-2e3a78976713","html_url":"https://github.com/xu-cheng/latex-action","commit_stats":{"total_commits":137,"total_committers":12,"mean_commits":"11.416666666666666","dds":"0.11678832116788318","last_synced_commit":"1ccd8e9a1ba76e30b547a1baf0e9c6d5ca33aea3"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xu-cheng%2Flatex-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xu-cheng%2Flatex-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xu-cheng%2Flatex-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xu-cheng%2Flatex-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xu-cheng","download_url":"https://codeload.github.com/xu-cheng/latex-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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","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":["github-actions","latex"],"created_at":"2024-07-31T16:01:19.165Z","updated_at":"2025-05-15T05:07:11.909Z","avatar_url":"https://github.com/xu-cheng.png","language":"Shell","funding_links":["https://github.com/sponsors/xu-cheng"],"categories":["Shell","Community Resources","Uncategorized","Build Tools"],"sub_categories":["Utility","Uncategorized","GitHub Actions"],"readme":"# latex-action\n\n[![GitHub Actions Status](https://github.com/xu-cheng/latex-action/workflows/Test%20Github%20Action/badge.svg)](https://github.com/xu-cheng/latex-action/actions)\n\nGitHub Action to compile LaTeX documents.\n\nIt runs in [a docker container](https://github.com/xu-cheng/latex-docker) with a full [TeXLive](https://www.tug.org/texlive/) environment installed.\n\nIf you want to run arbitrary commands in a TeXLive environment, use [texlive-action](https://github.com/xu-cheng/texlive-action) instead.\n\n## Inputs\n\nEach input is provided as a key inside the `with` section of the action.\n\n* `root_file`\n\n    The root LaTeX file to be compiled. This input is required. You can also pass multiple files as a multi-line string to compile multiple documents. Each file path will be interpreted as bash glob pattern. For example:\n    ```yaml\n    - uses: xu-cheng/latex-action@v3\n      with:\n        root_file: |\n          file1.tex\n          file2.tex\n    ```\n\n* `working_directory`\n\n    The working directory for this action.\n\n* `work_in_root_file_dir`\n\n    Change directory into each root file's directory before compiling each documents. This will be helpful if you want to build multiple documents and have the compiler work in each of the corresponding directories.\n\n* `continue_on_error`\n\n    Continuing to build document even with LaTeX build errors. This will be helpful if you want to build multiple documents regardless of any build error. Noted that even with this input set, this action will always report failure upon any build error. If you want to prevent the GitHub action job also from failure, please refer to [the upstream document](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error).\n\n* `compiler`\n\n    The LaTeX engine to be invoked. By default, [`latexmk`](https://ctan.org/pkg/latexmk) is used, which automates the process of generating LaTeX documents by issuing the appropriate sequence of commands to be run.\n\n* `args`\n\n    The extra arguments to be passed to the LaTeX engine. By default, it is `-pdf -file-line-error -halt-on-error -interaction=nonstopmode`. This tells `latexmk` to use `pdflatex`. Refer to [`latexmk` document](http://texdoc.net/texmf-dist/doc/support/latexmk/latexmk.pdf) for more information.\n\n* `extra_system_packages`\n\n    The extra packages to be installed by [`apk`](https://pkgs.alpinelinux.org/packages) separated by space. For example, `extra_system_packages: \"inkscape\"` will install the package `inkscape` to allow using SVG images in your LaTeX document.\n\n* `extra_fonts`\n\n    Install extra `.ttf`/`.otf` fonts to be used by `fontspec`. You can also pass multiple files as a multi-line string. Each file path will be interpreted as bash glob pattern. For example:\n    ```yaml\n    - uses: xu-cheng/latex-action@v3\n      with:\n        root_file: main.tex\n        extra_fonts: |\n          ./path/to/custom.ttf\n          ./fonts/*.otf\n    ```\n\n* `pre_compile`\n\n    Arbitrary bash codes to be executed before compiling LaTeX documents. For example, `pre_compile: \"tlmgr update --self \u0026\u0026 tlmgr update --all\"` to update all TeXLive packages.\n\n* `post_compile`\n\n    Arbitrary bash codes to be executed after compiling LaTeX documents. For example, `post_compile: \"latexmk -c\"` to clean up temporary files.\n\n* `texlive_version`\n\n    The version of TeXLive to be used. Supported inputs include 2020, 2021, 2022, 2023, 2024, and latest. By default the latest TeXLive is used. This input cannot co-exist with `docker_image` input. An example to use this input:\n    ```yaml\n    - uses: xu-cheng/latex-action@v3\n      with:\n        root_file: main.tex\n        texlive_version: 2022\n    ```\n\n* `docker_image`\n\n    Custom which docker image to be used. Only [latex-docker images](https://github.com/xu-cheng/latex-docker/pkgs/container/texlive-full) are supported. For example if you want to pin the docker image:\n    ```yaml\n    - uses: xu-cheng/latex-action@v3\n      with:\n        root_file: main.tex\n        docker_image: ghcr.io/xu-cheng/texlive-full:20230801\n    ```\n\n**The following inputs are only valid if the input `compiler` is not changed.**\n\n* `latexmk_shell_escape`\n\n    Instruct `latexmk` to enable `--shell-escape`.\n\n* `latexmk_use_lualatex`\n\n    Instruct `latexmk` to use LuaLaTeX.\n\n* `latexmk_use_xelatex`\n\n    Instruct `latexmk` to use XeLaTeX.\n\n## Example\n\n```yaml\nname: Build LaTeX document\non: [push]\njobs:\n  build_latex:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Set up Git repository\n        uses: actions/checkout@v4\n      - name: Compile LaTeX document\n        uses: xu-cheng/latex-action@v3\n        with:\n          root_file: main.tex\n      - name: Upload PDF file\n        uses: actions/upload-artifact@v4\n        with:\n          name: PDF\n          path: main.pdf\n```\n\n## FAQs\n\n### How to use XeLaTeX or LuaLaTeX instead of pdfLaTeX?\n\nBy default, this action uses pdfLaTeX. If you want to use XeLaTeX or LuaLaTeX, you can set the `latexmk_use_xelatex` or `latexmk_use_lualatex` input respectively. For example:\n\n```yaml\n- uses: xu-cheng/latex-action@v3\n  with:\n    root_file: main.tex\n    latexmk_use_xelatex: true\n```\n\n```yaml\n- uses: xu-cheng/latex-action@v3\n  with:\n    root_file: main.tex\n    latexmk_use_lualatex: true\n```\n\nAlternatively, you could create a `.latexmkrc` file. Refer to the [`latexmk` document](http://texdoc.net/texmf-dist/doc/support/latexmk/latexmk.pdf) for more information.\n\n### How to enable `--shell-escape`?\n\nTo enable `--shell-escape`, set the `latexmk_shell_escape` input.\n\n```yaml\n- uses: xu-cheng/latex-action@v3\n  with:\n    root_file: main.tex\n    latexmk_shell_escape: true\n```\n\n### Where is the PDF file? How to upload it?\n\nThe PDF file will be in the same folder as that of the LaTeX source in the CI environment. It is up to you on whether to upload it to some places. Here are some example.\n* You can use [`@actions/upload-artifact`](https://github.com/actions/upload-artifact) to upload a zip containing the PDF file to the workflow tab. For example you can add\n\n  ```yaml\n  - uses: actions/upload-artifact@v4\n    with:\n      name: PDF\n      path: main.pdf\n  ```\n\n  It will result in a `PDF.zip` being uploaded with `main.pdf` contained inside.\n\n* You can use [`@softprops/action-gh-release`](https://github.com/softprops/action-gh-release) to upload PDF file to the Github Release.\n* You can use normal shell tools such as `scp`/`git`/`rsync` to upload PDF file anywhere. For example, you can git push to the `gh-pages` branch in your repo, so you can view the document using Github Pages.\n\n### How to add additional paths to the LaTeX input search path?\n\nSometimes you may have custom package (`.sty`) or class (`.cls`) files in other directories. If you want to add these directories to the LaTeX input search path, you can add them in `TEXINPUTS` environment variable. For example:\n\n```yaml\n- name: Download custom template\n  run: |\n    curl -OL https://example.com/custom_template.zip\n    unzip custom_template.zip\n- uses: xu-cheng/latex-action@v3\n  with:\n    root_file: main.tex\n  env:\n    TEXINPUTS: \".:./custom_template//:\"\n```\n\nNoted that you should NOT use `{{ github.workspace }}` or `$GITHUB_WORKSPACE` in `TEXINPUTS`. This action works in a separated docker container, where the workspace directory is mounted into it. Therefore, the workspace directory inside the docker container is different from `github.workspace`.\n\nYou can find more information of `TEXINPUTS` [here](https://tex.stackexchange.com/a/93733).\n\n### It fails due to `xindy` cannot be found.\n\nThis is an upstream issue where `xindy.x86_64-linuxmusl` is currently missing in TeXLive. To work around it, try [this](https://github.com/xu-cheng/latex-action/issues/32#issuecomment-626086551).\n\n### It fails to build the document, how to solve it?\n\n* Try to solve the problem by examining the build log.\n* Try to build the document locally.\n* You can also try to narrow the problem by creating a [minimal working example][mwe] to reproduce the problem.\n* [Open an issue](https://github.com/xu-cheng/latex-action/issues/new) if you need help. Please include a [minimal working example][mwe] to demonstrate your problem.\n\n[mwe]: https://tex.meta.stackexchange.com/questions/228/ive-just-been-asked-to-write-a-minimal-working-example-mwe-what-is-that\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxu-cheng%2Flatex-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxu-cheng%2Flatex-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxu-cheng%2Flatex-action/lists"}