[Solved] It is possible to have conditionnal block in a separate yaml metadata file ?

[arnome-uBe]

Hi there,
First, thanks for this great tool. I use pandoc very regularly, and it's very useful. I try to automate a generation of a book written in different markdown files to 5 different formats (HTML, PDF, DOCX, ODT, EPUB) at the same time using pandoc and GitLab CI/CD. It's already done by others, but I want to understand the process.

I read here that Pandoc supports a separate YAML metadata file with conditional options like this:

---
title: "Some Title"
subtitle: "Markdown est vraiment formidable"
author: 
  -  Jane Doe
date: "2026-07-10"
---
# HTML settings
---
if: format == "html"
language: "fr-FR"
number-sections: true  
number-offset: 0
toc: true
toc-depth: 3
---
# PDF settings
---
if: format == "pdf"
header-includes: |
  \usepackage[default]{sourcesanspro}
  \usepackage[T1]{fontenc}
number-sections: true  
number-offset: 0
toc: true
toc-depth: 3
mainfont: "Calibri"
classoption: "a4paper"
geometry: margin=2cm
colorlinks: true
---
# EPUB settings
---
if: format == "epub"
number-sections: true  
number-offset: 0
---

This is my metadata file, and here are the pandoc options for html index file:

pandoc ./sources/*.md \
    --from="markdown+smart" \
    --to=html \
    --output="./_build/html/index.html" \
    --standalone=true \
    --template="./templates/html/elegant_bootstrap_menu.html" \
    --metadata-file="./metadata.yml"

but it does not work as expected. The HTML conditional block is not considered.
So, are conditional blocks allowed, and is my file malformed, or is it not possible to use conditional blocks as I expected?

Best regards,
arnome

[jgm]

This business with conditionals (if: format == "pdf") is not supported by pandoc itself:

# HTML settings
---
if: format == "html"
language: "fr-FR"
number-sections: true  
number-offset: 0
toc: true
toc-depth: 3
---
# PDF settings
---
if: format == "pdf"
header-includes: |
  \usepackage[default]{sourcesanspro}
  \usepackage[T1]{fontenc}
number-sections: true  
number-offset: 0
toc: true
toc-depth: 3
mainfont: "Calibri"
classoption: "a4paper"
geometry: margin=2cm
colorlinks: true
---
# EPUB settings
---
if: format == "epub"
number-sections: true  
number-offset: 0
---

Perhaps some other tool that wraps pandoc allows this. But the site you link to has the air of AI generated slop.

[jgm]

Note that it is definitely possible to conditionally inject things into metadata depending on the format, but you'd have to use a Lua filter to do that.

It would even be possible to write a general filter that allowed you to do something like this:

if:
  format: epub
  mainfont: "Calibri"

Please refer to the pandoc manual and the manual on Lua filters for reliable documentation.

[arnome-uBe]

@jgm thanks for your reply. I realize that my source is potentially an AI-generated site after my post; sorry...
I guess the best way to have correct settings for my setup is to use custom templates.

Many thanks for your work, John.

Have a nice day.
Best regards,
arnome

[jgm]

You can also pass in variables via the command line (see --variable); so, in the command where you emit epub, you can set the font and such things using variables on the command line. This makes more sense than putting them in metadata, since they are not metadata conceptually. You can also use a "defaults file" that sets all the defaults for your target format - see the docs on these.

[arnome-uBe]

I agree, it's not metadata but the settings part. I will use a YAML defaults file for each format; that's precisely what I'm looking for, thank you.

[arnome-uBe]

Hi,
I just tried the --defaults combined to the --data-dir options but it does not work.

What I do in my local directory :

$> mkdir -p ./pandoc/defaults
$> ls
pandoc/
metadata.yaml
my_book.md

I set a YAML default file for pdf output in this directory:

$> ls ./pandoc/defaults
pdf.yaml

First, I try this command:

pandoc my_book.md --from=markdown --data-dir="./pandoc" --defaults="pdf" --metadata-file=metadata.yaml --to=pdf --output="my_book.pdf"

But it leads to this error: « Multiple YAML documents encountered »

So I tried to set the metadata file in the default YAML PDF file like this:

metadata-file: metadata.yaml

but it leads exactly to the same error.

In my understanding, pandoc parser refuses multiple YAML files, but in this case, one is for metadata and the other is for default settings. I don't understand this error because it's possible to set the metadata file as default option in the default file according to the documentation.

What do I do wrong? Is the default PDF must be written in JSON then?

Thank you.
Best regards,
arnome

PS : here is my pdf.yaml file:

---
metadata-file: metadata.yaml
pdf-engine: xelatex
template: "./pandoc/templates/pdf/eisvogel.latex"
include-in-header:
  - ${.}/inc.tex
lua-filter: "./pandoc/scripts/pagebreak.lua"
number-sections: true  
number-offset: 0
toc: true
toc-depth: 3
toc-title: "Table des matières"
toc-own-page: true
cover-image: "./images/book-cover.png"
titlepage: true
prepend-titlepage: "./images/book-cover.pdf"
titlepage-background: "./images/background.pdf"
titlepage-text-color: "333333"
titlepage-rule-color: "00737C"
mainfont: "Calibri"
classoption: "a4paper"
geometry: "margin=2cm"
colorlinks: true
---

[wlupton]

I think it's the second --- that's triggering this. It introduces a new document. Either omit it or use ... to terminate the doc. Actually I don't think you need the opening --- either (but perhaps including it is good practice).

[arnome-uBe]

Thank you @wlupton, that's my error. It works great now. I'm just disappointed with the choice of all specific format options that can't be set in the target default file.
For example, all this options:

over-image: "./images/book-cover.png"
prepend-titlepage: "./images/book-cover.pdf"
titlepage-background: "./images/background.pdf"
mainfont: "Open Sans"
papersize: "A4"
titlepage: true
titlepage-text-color: "333333"
titlepage-rule-color: "00737C"
toc-title: "Table des matières"
toc-own-page: true
colorlinks: true

are rejected by the pandor parser in the default pdf.yaml file but accepted in the metadata.yaml file. For me, it's not really metadata, but perhaps I'm wrong.

Best regards,
arnome

[wlupton]

Defaults files specify command-line options, so to set metadata you need to add a metadata entry, e.g.,

 metadata:
  toc-title: Table of Contents

https://pandoc.org/MANUAL.html#reader-options-1

[arnome-uBe]

@wlupton I miss that possibility... Thank you! It's clear to me now.