How do I use option file-scope to reset example numbering every chapter?

[adamiturabi]

Description

In this pandoc issue, it is suggested to use option --file-scope to reset numbered examples for every chapter:
jgm/pandoc#10940

So if I have chapter1.qmd:

# Chapter1

(@) An example

And chapter2.qmd:

# Chapter2

(@) Another example

Then how should I set this option?

I tried the following _quarto.yml file but it doesn't seem to work:

project:
  type: book

book:
  title: "Hello"
  author: "Norah Jones"
  date: "8/22/2026"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd

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

file-scope: true

I also tried putting the file-scope under the pdf format.

[CasperKristiansson]

file-scope: true is already the right Quarto setting; moving it under pdf won’t change this. The catch is that Pandoc only resets (@) examples when it receives multiple input files, while Quarto combines a book before the final single-document conversion.

For book-aware numbering, use Quarto’s native example blocks instead:

::: {#exm-chapter-one}
## An example

Example text.
:::

In a numbered book these render per chapter, such as Example 1.1 and Example 2.1. If you specifically need the literal (1) style to restart in every chapter, file-scope can’t do that in a Quarto book; that needs custom filtering rather than a different YAML placement.

[mcanouil]

In addition to this, numbering beside list is done by Quarto's own system, not Pandoc.

• https://quarto.org/docs/authoring/callouts.html#cross-references
• https://quarto.org/docs/authoring/cross-reference-options.html

In my experience, the easiest approach/workaround is currently with Typst book (Quarto 1.9 and later version), but that's still involving.

There are currently no native way to do what you want here.

There are probably LaTeX workarounds similar to:

• https://github.com/orgs/quarto-dev/discussions/1283

[adamiturabi]

Thank you. I've started to use exm divs to replace the @ numbered example lists. But I'm trying to fake the look and feel of the numbered example lists, while retaining Quarto's crossref capability.

The look and feel that I am trying to recreate is that numbered examples are lists so if there are multiple lines they are all indented. And the text of the first line will be on the same line as the listing number.

The use case is for linguistic examples where the first line is the actual text and the subsequent lines are transcriptions/transliterations/translations.

So I put a list inside the exm div and wrote a filter to track and modify its start value, and reset the start value at every level 1 heading.

Here is my filter:

-- Tracks the current example number
local example_counter = 1

-- intercept headers to check for manual resets or specific levels
function Header(el)
    -- Reset on Header level 1 (e.g., # New Chapter)
    if el.level == 1 then
        example_counter = 1
    end

    -- Also check for a custom attribute like: # Header { .reset-examples }
    if el.classes:includes('reset-examples') then
        example_counter = 1
    end

    return el
end

-- Intercept custom Div containers
function Div(div)
    -- Check for an attribute like: ::: { .reset-examples } or ::: { reset-counter="true" }
    if div.classes:includes('reset-examples') or div.attributes['reset-counter'] == 'true' then
        example_counter = 1
    end
    if div.classes:includes('myex') then
      -- Filter only the OrderedLists inside this specific div
      local filter = {
        OrderedList = function(ol)
          if ol.style == "Decimal" then -- don't modify sub-lists. those will be alpha or roman
            -- Modify the ordered list here
            if FORMAT:match 'latex' then
              ol.start = example_counter
            elseif FORMAT:match 'html' then
              -- Create the opening and closing raw HTML tags
              -- add class myex for CSS formatting
              local open_tag = pandoc.RawInline('html', '<ol start="' .. example_counter .. '" class="myex" type="1">')
              local close_tag = pandoc.RawInline('html', '</ol>')
              local wrapped_blocks = pandoc.List{open_tag}

              -- Iterate through each item (which is a list of blocks) in the ordered list
              for _, item in ipairs(ol.content) do
                table.insert(wrapped_blocks, pandoc.RawBlock('html', '<li>'))
                for _, block in ipairs(item) do
                  table.insert(wrapped_blocks, block)
                end
                table.insert(wrapped_blocks, pandoc.RawBlock('html', '</li>'))
              end

              table.insert(wrapped_blocks, end_tag)
              ol = wrapped_blocks
            end

            -- Increment our internal tracking counter
            example_counter = example_counter + 1
          end
          return ol
        end
      }

      return pandoc.walk_block(div, filter)
    end
    return div
end

Sample chapter qmd file:

# Introduction

Lorem ipsum

::: {.myex #exm-abcd}
(4) Example1 text
    _Its transcription._
    «Its translation.»
:::

@exm-abcd shows ...

::: {.myex #exm-efg}
(6) a. Example 2a text
       _Its transcription._
    b. Example 2b text
       _Its transcription._

    «Its translation.»
:::

@exm-efg shows ...

Here is the output (in PDF, HTML is similar):

I would like to ask if there is any way to remove the Example titles (circled in red). I set the exm-title to "" to remove as much as possible. But ideally the whole line would be removed along with any vertical space that it would take. Here is my config:

crossref:
  exm-prefix: Example
  exm-title: ""

By the way, I also wrote another filter to reset Pandoc's numbered example lists at every chapter for PDF. I've pasted it here: jgm/pandoc#10940 (comment)

Thank you for all your help.

[mcanouil]

I would suggest to use custom cross references and use the custom AST node instead of trying to modify example (that should still be doable but I'm not completely sure that all the pieces are in Lua).

• https://quarto.org/docs/advanced/quarto-ast.html#cross-referenceable-elements

[adamiturabi]

Thank you. I also wanted to give a general update:

Pandoc has added an option (1@foo) to explicitly reset the numbered example list count. More details here:jgm/pandoc#10940 (comment)