Search code examples
r-markdownpandocquarto

Is it possible in quarto to create custom cross-references to callout blocks?


Task

I'm using quarto to write an online book and need to mimic the environments and counters of a published book. The latter employs five custom framed environments (examples, exercises, remarks, theorems, definitions) with a joined counter (within the chapter).

I'm considering to use the readily available callout blocks for these because these are styled quite nicely by default. I haven't been successful, though, to create a custom counter for these callout blocks so that I can cross-reference from the text. Is there a way to do so?

(Remark: I've also tried to do this via standard amsthm environments provided through quarto, see Shared counter in quarto for exercises, examples, etc.)

Demo

I would have hoped that something like the following existed so that I can create a new #callout counter. But I couldn't find infrastructure for this:

The first definition is @callout-1.

:::{.callout-note}
## Definition {#callout-1}
This should be Definition 1.1.
:::

It is followed by the first example, @callout-2

:::{.callout-tip}
## Example {#callout-2}
This should be Example 1.2.
:::

Because this doesn't work like this quarto renders this to:

callout block example as rendered by quarto

But what I'm looking for is a result like this:

callout block example with desired rendered (mimicked manually)


Solution

  • I was looking for a workaround in a similar that allows me to define groups of jointly numbered environments (for html and pdf) without extra hacks. I put my solution in an extension. It does for the time being only support crossreference by \ref, and maybe it becomes obsolete with quarto 1.4? You can modify the appearance / colors for each type of environment from the yaml.

    filters:
      - custom-numbered-blocks
    custom-numbered-blocks:
      groups: 
        thmgroup: 
          boxstyle: foldbox.simple
          collapse: false
      classes:
        Example:
          group: thmgroup
        Definition:
          group: thmgroup
          colors: [cce7b1, 86b754]
    

    Then

    # First Section
    
    The first definition is Definition \ref{mydef}
    
    ::: {.Definition #mydef}
    
    This should be Definition \ref{mydef}
    
    :::
    
    It is followed by the first example, Example \ref{myexpl}
    
    ::: {.Example #myexpl}
    
    ### an example for Definition \ref{mydef}
    
    This should be Example \ref{myexpl}
    :::
    

    renders in html

    rendered example, html

    or in pdf

    rendered example, pdf

    To change the overall appearance of the boxes, you would currently need to modify a css / tex file.

    The extension is here: https://github.com/ute/custom-numbered-blocks