Creating new callout types (and sharing as an extension)?

[jreades]

Description

I'm wondering if it's possible to create new, or extend existing, callout types and then to share/deploy them via an extension?

For context: I've got a set of iPython teaching notebooks that make use of the built-in CSS classes (alert alert-block... and the you've got the alert-success, alert-danger, alert-warning selectors within that) to achieve a few different things:

1. Present a sense of the difficulty-level (Low / Medium / Hard / Mind-Blowing), each of which has an associated icon and some text that is shared (e.g. **<ICON> Difficulty Level**) and some that is not (a brief description of why the next section is given that rating).
2. Highlight points of connection to other content covered in the module (this is the alert-note class) again with an icon (the chain-link) and a mix of standard / custom text.

Currently these are notebooks, but I've realised that I could manage them quite effectively as QMD files and want to swap to rendering the ipynb file from the QMD instead of maintaining the notebook file as-is. I use these alert-blocks enough that I don't want to be continually tweaking a {.callout-tip} and what-have-you, but would rather have, say, a {.notebook-link} or {.notebook-hard} callout that renders correctly depending on the context.

The logic for sharing this as an extension is that my colleagues (or anyone else who was interested) could then use this same approach for a more standardised presentation of our teaching materials.

I can't quite figure how to do this based on the materials I've found at docs/authoring/callouts.html and docs/authoring/callouts.html and quarto-dev/quarto-cli/discussions/4755. Any guidance gratefully received.

[cscheid]

This will need to be done in a Lua filter. You'd need to write a filter that catches divs, detects the class "notebook-link", and then emit a callout programmatically. That filter would look something like this:

function Div(div)
  if div.classes:includes("notebook-link") then
    -- create callout here, something like the following.
    -- You'll need to inspect the contents of the 
    return quarto.Callout({
      type = "note",
      content = div.content
      title = "Notebook link"
    })
  end
end

Then you can create an extension that exposes the filter.

Documentation on filter extensions, and Lua development for Quarto.

[jreades]

I've been working on this and have made some progress: I now have my own callout types (e.g. casa-note, casa-warning, etc. -- casa is the name of our lab) based on your example above. When rendering to HTML they just replicate the output of the .callout-X classes and I felt quite proud of the fact I worked out how to pull the title out and pass that to the Quarto callout constructor.

So right now I'm able to take this:

::: {.casa-important}
## Something Important

This is important.
:::

And if I'm outputting to HTML then this produces output that matches the {.calloutput-important} output. However, I realised that my main 'issue' is actually that there's no calloutIpynb handler function in the ./filters/main.lua dispatcher that renders an HTML div into a notebook. It just falls through to the simpleCallout which renders as a blockquote.

So I currently have a pandoc Div that looks like this:

Div ("",["alert alert-danger"],[]) [Plain [Emph [Str "💡",Str "Something",Space,Str "Important"]],Para [Str "This",Space,Str "is",Space,Str "important."]]

But I've been Googling for half the day and cannot figure out how to force this to render as an HTML DIV embedded within a notebook instead of vanilla Markdown. What I was hoping to see was a way to take the above and turn it into:

<div class="alert alert-danger">
<em>&#128161 Something Important</em>
<p>This is important.</p>
</div>

I'm guessing the issue is that a vanilla notebook wouldn't normallycontain raw HTML and pandoc is doing exactly what it should be. So it seems to me that I need to force this Div to be returned as HTML and then inject that into a Notebook markdown cell, but I can't find out how to do this.

[jreades]

Naturally, as soon as I post this I have a brainwave and am now much closer to a solution:

I've added the following to my calloutIpynb function:

    doc = pandoc.Pandoc({ calloutDiv })
    html = pandoc.write(doc, 'html')
    return html:gsub('&','&')

This returns an actual Div such as:

<div class="alert alert-danger">
<strong>&amp;#128161;Something Important</strong>
<p>This is important.</p>
</div>

But now the output is being escaped:

\<div class="alert alert-success"\> \<strong\>&#128161;A tip…\</strong\>
\<p\>This is a tip.\</p\> \</div\>

Do I need to specify this as a Raw cell or something?

[jreades]

Aaaaand, finally answering my own question after a good night's sleep: pandoc.Rawinline('html', <div content as html>).

Going to mark this as answered now (thank you both!) and work on polishing up the code before proposing it as a possible extension to the quarto.Callout library.

[cscheid]

For future readers, small typo there: It's pandoc.RawInline, not pandoc.Rawinline (but the point is exactly right)

[danieltomasz]

Hi @jreades in the past there were an interesting discussion about callouts (how to convert Obsidian/github callouts to the quarto/pandoc type, you might find it useful)
#6550

[jreades]

Thank you very much, that’s really helpful! Will check these out and see how I do — Lua definitely not part of my knowledge base but I usually get there in the end.

[jreades]

My long term goal is to replace a pair of weekly Jupyter notebooks (one with questions, one with answers) and lots of shared content that is a pain to keep in synch with a single QMD that has the question and answer sections as panel tab-sets. i will probably manage the split into two Ipynbs using a post-render script. Well, until I realise that doesn’t work. ;-)