Can I access pandoc options in a shortcode?

[bergsmat]

Description

In my document, I'm creating my own pdf table of contents in a custom location. Rather than hard-code tocdepth, I do this:

# Table of Contents

\addtocontents{toc}{\protect\setcounter{tocdepth}{ {{< meta toc-depth >}} }}
\renewcommand{\contentsname}{}
\tableofcontents

That's my use case. For my MWE, I use the quarto book template, with _quarto.yml like this:

project:
  type: book

book:
  title: "example2"
  author: "Norah Jones"
  date: "1/3/2025"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

toc-depth: 0

And then at the end of index.qmd I add this line:

TOC depth is {{< meta toc-depth >}}

quarto render gives the helpful message: "Unknown meta key toc-depth specified in a metadata Shortcode."

I know toc-depth: 0 is placed correctly because the resulting html document has an empty table of contents. I think the shortcode is otherwise formatted correctly, because it works if I change all toc-depth to foo. From #7711, I gather that toc-depth may be a pandoc option rather than a true "meta" value. Is there shortecode syntax to access toc-depth?

[mcanouil]

You should use raw code block to include raw content as documented in https://quarto.org/docs/authoring/markdown-basics.html#raw-content

Have you considered using partials and templates?
https://quarto.org/docs/journals/templates.html#latex-partials

Assuming you'll read Quarto and Pandoc documentation to know the name of the options and their locations:

• https://github.com/mcanouil/quarto-lua-env

Regarding the error, that's because books are complex projects and that the meta shortcode cannot access some if not all global options likely because Quarto uses both TypeScript and LUA for processing of books.

What's the purpose of setting toc-depth: 0? Why not set toc: false?

[bergsmat]

@mcanouil Thanks for your response.

The purpose of setting toc-depth: 0 is merely to demonstrate that this option is correctly placed in the hierarchy. toc-depth, not toc, is used effectively in my motivating example. Values of 1 or greater would not give a visual difference in the template output, and so would be an inconclusive test that this option is operational as implemented.

Thanks for your other suggestions. I personally have no problem considering templates, but trying to keep this as simple as possible for a large user group.

Can pandoc options in _quarto.yml be defined in terms of other values in the same file? If so it would be an easy solution for me to share with others:

foo: 4
toc-depth: !expr foo

or similar.

[mcanouil]

The use of !expr is not really recommended as it's a knitr specific feature that does not work everywhere.
toc-depth expects a number so you cannot use !expr expression or any markdown (i.e., shortcode).

but trying to keep this as simple as possible for a large user group.

Make a format extension with your custom template then.

---

Caution

YAML offers a system of reference but this is not well supported in Quarto and should be used by users with sufficient knowledge as they will be on their own when using this.
Using this system won't make the linter happy.

• our YAML validator doesn't work well with YAML references #8762

• _quarto.yml

  toc-depth: &toc_depth 0
  my-toc-depth: *toc_depth

• index.qmd

  ---
  title: "Quarto Playground"
  format: html
  toc: true
  ---
  
  {{< meta my-toc-depth >}}
  
  ## Heading 1
  
  ### Heading 2

[cderv]

I gather that toc-depth may be a pandoc option rather than a true "meta" value. Is there shortecode syntax to access toc-depth?

toc-depth is among Pandoc Writer option, and it is not really a metadata within Pandoc. It will be read as option by Pandoc, and the different writers may set a template variable toc-depth to its value, but in the meantime it is not a Meta within Pandoc AST. It can be set using command line --toc-depth in Pandoc, but also using YAML field through default file. And Quarto will pass it to Pandoc this way when you set it in configuration.

In LUA, writer options can be retrieved using PANDOC_WRITER_OPTIONS global variable which contains toc_depth among other values

So you could write a shortcode using Lua that retrieve this value. Or you could use https://github.com/mcanouil/quarto-lua-env as recommended above as described in the README.

Example

---  
title: "Sample Document"  
format: html
toc-depth: 2
filters:
  - lua-env
---

TOC DEPTH: {{< meta lua-env.pandoc.PANDOC_WRITER_OPTIONS.toc_depth >}}

This may be included in a generic Quarto feature at some point. You can follow

• Expose all LUA variables to Quarto meta shortcode #4770

[bergsmat]

Thanks all for the detailed discussion! @cderv, I understand the lua-env approach and I am now also subscribed to #4770, thanks. You also say

So you could write a shortcode using Lua that retrieve this value.

I am intrigued, and wish to explore further. Would I just say {{< meta toc-depth >}} in my document, and then write a filter (to be identified in _quarto.yml) that somehow traps this "request" and substitutes the implied pandoc writer option?

[mcanouil]

I am intrigued, and wish to explore further. Would I just say {{< meta toc-depth >}} in my document, and then write a filter (to be identified in _quarto.yml) that somehow traps this "request" and substitutes the implied pandoc writer option?

He was suggesting you to do the same thing as my lua-env extension (filter+shortcode), but targeted for your use case.

[bergsmat]

@mcanouil Thanks. I will have to learn more about this approach. I'm especially interested whether it can be implemented as just a local file, rather than as a full extension that needs to be installed.

[mcanouil]

The same way as filters: https://quarto.org/docs/extensions/filters.html#activating-filters

shortcodes: 
  - your-script.lua
filters:
  - your-script.lua

[bergsmat]

@mcanouil, @cderv: thanks for the help! This is an elegant and portable solution. It solved my problem.

[cderv]

I'm especially interested whether it can be implemented as just a local file, rather than as a full extension that needs to be installed.

To be clear, extension are local. You don't need to install them if you create the extension structure locally to your project. You can have them locally to your project and never published them.

It is just a convenient way to access some Lua function as quarto will look in local extension directory for shortcodes for example (without needing to declaring them in a file).

Anyhow, both work. 😄

[bergsmat]

@cderv I did not realize that. Thanks for clarifying.