Customise appearance of theorems and related blocks in html

[giabaio]

Description

Hi all, I have mentioned this in a reply to issue #317 but haven't seen much activity there, so trying again here. I have a book, in which I want to customise the appearance of the "example" blocks. In other words, when I do

::: {#exm-label}
## Some title
the text of the example...

this gets rendered as
Example X (Some title) the text of the example...

Now, I would like to modify the appearance and remove the brackets around the title tag --- I can customise some elements in css (like change the font or control colors/size, using .example .theorem-title {...}. But I couldn't control the brackets. I tried hacking the theorems.lua filter, but to no avail.

Is there a way to do it?
BTW: my book uses the CRC template, which is fairly structured, but I have tried on a minimal example with just a book and the same happened --- this is not about the template, I think; it's just how (presumably filters?) parse the text into the final format and, clearly, I haven't been clever enough to figure how to change it...

Any ideas?
Thanks

[mcanouil]

I don't think there is an easy way.

Most customisations like this would involve working with a Lua filter because here you need to process the content.

Now there are alternatives (alone or mixed):

• custom callout https://quarto.org/docs/prerelease/1.3/ast.html#example-callouts (or https://github.com/coatless-quarto/custom-callout)
• custom cross-reference (https://quarto.org/docs/authoring/cross-references-custom.html)

[giabaio]

Thank you @mcanouil. Can I just follow up quickly? What is the lua filter that controls the appearance of the theorem/example? Like I said, theorems.lua doesn't seem to have an effect on the output (unless in the tests I've made...). Is there anywhere else I should look? Thanks!

[mcanouil]

It's not that simple because of the cross-reference system.
There are several pieces:

• https://github.com/quarto-dev/quarto-cli/blob/d40b8ec70e62245bc691aa9c3ca1eae1e6301c3b/src/resources/filters/customnodes/theorem.lua
• https://github.com/quarto-dev/quarto-cli/blob/acb040fb519495d668adb1dacd510dda6c6576aa/src/resources/filters/crossref/theorems.lua
• https://github.com/quarto-dev/quarto-cli/blob/e5faa8d74dd9f9b41505e1130ce913e9d9e38ba6/src/resources/filters/quarto-pre/theorems.lua

I cannot guaranty that all the processing is done only in Lua and in those files.

[giabaio]

Thank you, @mcanouil. In case this is helpful, a very quick test suggests that modifying src/resources/filters/crossref/theorem.lua in the function captionPrefix as

function captionPrefix(name, type, theoremType, order) 
  local prefix = title(type, theoremType.title)
  table.insert(prefix, pandoc.Space())
  tappend(prefix, numberOption(type, order))
  if #name > 0 then
    table.insert(prefix, pandoc.Str(". ")) 
    tappend(prefix, name)
    table.insert(prefix, pandoc.Str("."))
  end
  return prefix
end

to replace the original

function captionPrefix(name, type, theoremType, order) 
  local prefix = title(type, theoremType.title)
  table.insert(prefix, pandoc.Space())
  tappend(prefix, numberOption(type, order))
  if #name > 0 then
    table.insert(prefix, pandoc.Space())
    table.insert(prefix, pandoc.Str("("))
    tappend(prefix, name)
    table.insert(prefix, pandoc.Str(")"))
  end
  return prefix
end

seems to do the trick (if I replace the code in the original file)... With this, the formatting is something like

Example 1.1. Significance testing. Blah blah blah...

which is pretty much what I wanted.

However, creating a new theorems.lua with these changes and adding it to the filters in my yml file as

filters: 
       - quarto
       - theorems.lua

does not work and the standard behaviour replaces the changes...
Even just creating a new .lua file with a random name does not work... Am I missing some obvious behaviour here? (I thought https://quarto.org/docs/extensions/filters.html indicated that it would be possible to run a customised filter after the standard one, which I understood would allow to modify the normal behaviour?).

Thanks!

[mcanouil]

Use format: native to see what the AST looks like.
Note that you are asking all Quarto filters to happen before your theorems.lua, so the input to it is not the same as it has been processed/changed already.
https://quarto.org/docs/prerelease/1.4/lua_changes.html#more-precise-targeting-of-ast-processing-phases

Note that you can't change any internal functions if that is what you are trying to do.
For example in R, even if you change the definition of a function (that was not scoped), you can't change the previous executions results:

f <- function (x) {
 sqrt(x)
}
(x <- f(9))
#> [1] 3

sqrt <- identity
(y <- f(9))
#> [1] 9
x
#> [1] 3

[giabaio]

Thanks. I think I don't know enough of lua and the underlying working of things, so that's certainly my fault/shortcoming...

I mean this is not such a huge deal for me, so I won't bother you much more with it --- I just thought this may be more important for others and that this discussion may help them... I see what you're saying here, so basically the results are already processed by the standard quarto machinery and thus adding a new filter does not change that behaviour (and neither does simply adding the new filter, because it gets overruled by the "standard" process)?

Like I said, it won't affect me in a way I can't bear, so I'll probably leave it --- and worst case scenario, I could create my own temporary version of quarto with the changes above to compile the whole thing and get the exact same format I want... That's hacky of course (and I probably won't bother)...

Thanks for looking into this!

[mcanouil]

To change the result (if possible), you would need to write the complete logic in a new filter and make this filter execute before "quarto".

Post-processing would also be a solution/workaround.