What is the correct way to render PDF using Github Actions?

[serkor1]

Description

Hi,

I am trying to create a Quarto book with the option to export it as PDF using Github actions. During the rendering I get all kinds of exciting errors, this is the last error:

> installing koma-script (1 of 1)
  Rc files read:
    NONE
  Latexmk: Nothing to do for 'index.tex'.
  Collected error summary (may duplicate other messages):
    pdflatex: gave an error in previous invocation of latexmk.
  
  Latexmk: Sometimes, the -f option can be used to get latexmk
    to try to force complete processing.
    But normally, you will need to correct the file(s) that caused the
    error, and then rerun latexmk.
    In some cases, it is best to clean out generated files before rerunning
    latexmk after you've corrected the files.
  
ERROR: 
compilation failed- missing packages (automatic installation failed)
ERROR: Error
    at Object.onComplete (file:///opt/quarto/bin/quarto.js:100251:91)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async renderFiles (file:///opt/quarto/bin/quarto.js:85612:16)
    at async renderProject (file:///opt/quarto/bin/quarto.js:86020:25)
    at async Command.actionHandler (file:///opt/quarto/bin/quarto.js:90654:32)
    at async Command.execute (file:///opt/quarto/bin/quarto.js:8111:13)
    at async Command.parseCommand (file:///opt/quarto/bin/quarto.js:8001:20)
    at async quarto (file:///opt/quarto/bin/quarto.js:126627:9)
    at async file:///opt/quarto/bin/quarto.js:126654:9
    at async mainRunner (file:///opt/quarto/bin/quarto.js:126519:9)
Error: Process completed with exit code 1.

This is the error I got before it:

> installing caption (1 of 1)
  This is XeTeX, Version 3.141592653-2.6-0.999996 (TeX Live 2024) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
ERROR: 
compilation failed- error
LaTeX Error: Something's wrong--perhaps a missing \item.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.6586 \end{CSLReferences}
                           

see /home/runner/work/SLmetrics/SLmetrics/docs/index.log for more information.
ERROR: Error
    at Object.onComplete (file:///opt/quarto/bin/quarto.js:100251:91)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async renderFiles (file:///opt/quarto/bin/quarto.js:85612:16)
    at async renderProject (file:///opt/quarto/bin/quarto.js:86020:25)
    at async Command.actionHandler (file:///opt/quarto/bin/quarto.js:90654:32)
    at async Command.execute (file:///opt/quarto/bin/quarto.js:8111:13)
    at async Command.parseCommand (file:///opt/quarto/bin/quarto.js:8001:20)
    at async quarto (file:///opt/quarto/bin/quarto.js:126627:9)
    at async file:///opt/quarto/bin/quarto.js:126654:9
    at async mainRunner (file:///opt/quarto/bin/quarto.js:126519:9)
Error: Process completed with exit code 1.

What am I doing wrong? I have followed all steps on https://quarto.org/docs/publishing/github-pages.html#github-action - there is no issues if I exclude the PDF, so it does work. It just doesn't work for the PDF version.

The _quarto.yaml and workflow files is provided below.

_quarto.yaml

project:
  type: book
book:
  title: '{SLmetrics}: Machine Learning Performance Evaluation on Steroids'
  subtitle: Version 0.3-1
  author: Serkan Korkmaz
  version: 0.3-1
  repo-url: https://github.com/serkor1/SLmetrics
  repo-branch: development
  repo-subdir: docs
  repo-actions:
  - edit
  - source
  - issue
  sharing:
  - twitter
  - facebook
  - linkedin
  sidebar:
    title: Documentation
  downloads:
  - pdf
  - epub
  chapters:
bibliography: references.bib
format:
  html:
    theme:
      light:
      - cosmo
      - theme-light.scss
      dark:
      - slate
      - theme-dark.scss
    fontsize: 18px
    mainfont: calibri
  pdf:
    documentclass: scrreprt
    keep-tex: true
    latex-auto-install: true
highlight-style: github
execute:
  freeze: auto
  cache: true

github actions .yaml

on:
  workflow_dispatch:
  push:
    paths: ['docs/**', '.github/workflows/build-docs.yaml', 'tools/doc-builders/build-yaml.py']
    branches-ignore:
      - stable
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

name: Build Docs

jobs:
  build-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      R_KEEP_PKG_SOURCE: yes

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          tinytex: true


      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: 'release'
        
      - name: Setup R dependencies
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          cache: 'always'
          packages:
            local::.
            deps::.
          extra-packages:
            any::MLmetrics
            any::mlr3measures
            any::yardstick
            any::bench
            any::tidyverse
            any::tidymodels
            any::stringi

      - name: Setup Python 
        uses: actions/setup-python@v5
        with:
          python-version: '3.12.x'
          cache: pip

      - name: "Setup Python dependencies"
        shell: bash
        run: |
          pip install -r tools/requirements.txt

      - name: Parse Roxygen files
        shell: Rscript {0}
        run: |

          # 1) create folders
          dir.create("docs/ref_regression")
          dir.create("docs/ref_classification")

          # 2) source builders
          source('tools/doc-builders/build-qmd.R')

      - name: Build YAML-file
        run: python tools/doc-builders/build-yaml.py

      - uses: r-lib/actions/setup-tinytex@v2  
      - run: tlmgr --version
      
      - name: Install additional LaTeX packages
        run: |
          tlmgr update --self
          tlmgr install titlesec
          tlmgr list --only-installed

      - name: Render docs
        uses: quarto-dev/quarto-actions/render@v2
        with:
          path: docs/
          
      - name: Publish docs
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
          path: docs/
          render: false
        

[cderv]

Does the PDF builds without error locally with TinyTeX distribution ?

From what I see in your action, you are installing TinyTeX twice two - I don't know if this is working well.

1. First one with Quarto as you set tinytex: true in the action.
2. Second time as you are using r-lib/actions/setup-tinytex@v2

Maybe try with only one ?

[mcanouil]

Do you have an empty bibliography by any chance?

[serkor1]

Yes! The bibliography is all empty at the moment! Is that the issue? 🤔

[mcanouil]

Yes, that's the Pandoc issue.

[mcanouil]

See:

• Why does render fail for a book with an empty list of references? #11785
• Pandoc issue: Document without citation doesn't get compiled jgm/pandoc#10185

The fix from Pandoc is not yet available to Quarto, thus the following is still opened:

• If you delete references.bib for from _quarto.yml latex rendering gives hard to understand error #11040

[mcanouil]

FYI, the fix is in Pandoc 3.5 and above.
Quarto 1.7 is currently using Pandoc 3.4:

• quarto-cli/configuration

  Line 14 in 7738833

  export PANDOC=3.4

[serkor1]

Oh! OK, that makes perfect sense. This is also why I couldn't find any issues - I was searching for something completely different! Was not aware that this was related to the reference! Sorry for bloating the discussion board!

Thank so you so much for your help!

[serkor1]

FYI, the fix is in Pandoc 3.5 and above. Quarto 1.7 is currently using Pandoc 3.4:

* https://github.com/quarto-dev/quarto-cli/blob/7738833da69fb2a15c35f9d754dc171f92f0d73e/configuration#L14

Are we waiting for a Quarto update, or can we force Pandoc 3.5 in our projects?

[mcanouil]

Are we waiting for a Quarto update,

Yes, but can't tell when

or can we force Pandoc 3.5 in our projects?

At your own risk and as Carlos likes to say "this will void the guarantee", i.e., Quarto has not been tested so you might fix the empty biblography issue but you might break everything else.

@serkor1 Go through the GitHub Discussion I've linked and that you've marked as the answer, there are workarounds.