Does anyone have a filter for alert / callout styling in PDF output?

[FeralFlora]

Since alerts are very minimally styled, they need to have styling applied using something like a filter. Without that, they're not really appealing to use.

Unfortunately, I haven't seen any such filter floating about, and I don't have the experience to create one myself at the moment.

So I was wondering if anyone here had come across or created such a filter for alert / callout styling?

[iandol]

Hm, I didn't notice this new extension, and I can't get it to work, so I must be doing something wrong. gfm is supposed to have this enabled but:

pandoc -f gfm -t html

> [!INFO]
> This is an informational message.

<blockquote>
<p>[!INFO] This is an informational message.</p>
</blockquote>

commonmark doesn't have it enabled but the output is identical:

> pandoc -f commonmark -t html

> [!INFO]
> This is an informational message.

<blockquote>
<p>[!INFO] This is an informational message.</p>
</blockquote>

How is this supposed to work?

---

You can also just use fenced divs; for HTML or ODT / DOCX you can use a fenced div with a class & custom-style to link to a CSS class or ODT/DOCX style for the callout. For Typst, I've used the gentle-clues package, and have some code to convert a fenced div to the Typst gentle-clues syntax directly (https://typst.app/universe/package/gentle-clues/), you can do the same sort of thing for LaTeX.

[FeralFlora]

Hm, I didn't notice this new extension, and I can't get it to work, so I must be doing something wrong. gfm is supposed to have this enabled but

How is this supposed to work?

I'm not sure. It was working in my earlier tests, but now it's not working for me either:

Testing commonmark vs commonmark+alerts, the result is the same:

[iandol]

Right, this is probably a regression. Worth submitting an issue and see what @jgm makes of it.

As an aside, I agree with a lot of the comments on the github issue that hijacking blockquotes is really not an ideal syntax. I think fenced divs are nicer from a syntax perspective...

[FeralFlora]

@iandol Reported here: #9824

[iandol]

Actually, when I tested I just copied from the Pandoc manual, but the manual is incorrect, there is no [!INFO] callout. Now if I use another callout I do now see this working:

pandoc -f gfm -t native

> [!tip]
> This is a tip

[ Div
    ( "" , [ "tip" ] , [] )
    [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ]
    , Para
        [ Str "This"
        , Space
        , Str "is"
        , Space
        , Str "a"
        , Space
        , Str "tip"
        ]
    ]
]

You tests were not working as the callout needs to be a block, you need newlines before and after the block:

➪ echo "\n> [!tip]\n" | pandoc -f gfm -t native
[ Div
    ( "" , [ "tip" ] , [] )
    [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ] ]
]

So this is working in fact. Now to style them requires a way to turn Pandoc native divs into formatted output, and that depends on the output format: for HTML just add CSS; for ODT/DOCX you need to also add the custom-style attribute (perhaps Pandoc should do that by default?); for Typst the div needs to turn into Typst markup depending on what package you'll use (same for LaTeX).

[FeralFlora]

Okay, glad we got that out of the way, and thanks for all your suggestions.
However, my main concern is PDF output. I should have mentioned that, but your insights are useful regardless, for me and others.

Am I right that a filter would be needed in this case? By using the alerts extension, I want to stay with the gfm alert syntax, which is also used in the Obsidian notetaking app.

[iandol]

I corrected the Pandoc manual alerts example here: #9826

[FeralFlora]

After much digging, I managed to find one pretty promising filter, but I haven't tested it yet: https://github.com/kdheepak/kdheepak.github.io/blob/8e6c244420fb09e2e4a44986e424ee7ed09e96ca/_quarto/alert.lua

Source: https://kdheepak.com/blog/pandoc-lua-filter-for-alerts/

[FeralFlora]

Seems like this filter is for divs. Is not working with gfm alert syntax for me.

[iandol]

Why not just use the fenced_div syntax to use that filter? The fenced_div AST is slightly easier to parse and it doesn't misuse the blockquote syntax semantically:

ε ➪ pandoc -f gfm+fenced_divs -t native

> [!tip]
> Some text

::: {.tip}
Some Text
:::

[ Div
    ( "" , [ "tip" ] , [] )
    [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ]
    , Para [ Str "Some" , Space , Str "text" ]
    ]
, Div
    ( "" , [ "tip" ] , [] )
    [ Para [ Str "Some" , Space , Str "Text" ] ]
]

Note the > [!tip] syntax introduces a title div and content div (useful for plain text or HTML outputs, not so much for other outputs) whereas the fenced div just has content. It isn't a big deal.

The other question is what output -- again lets say I want PDF and choose Typst as the PDF engine then I want the syntax to match a Typst construct, not some generic title and emoji output. For Typst you would want something like #tip[Some Text], for LaTeX you'd need a specific environment (e.g. https://github.com/chdemko/pandoc-latex-admonition), for ODT/DOCX you'd need to add a custom-style. Each output format has an optimal conversion, so just asking for a filter is an underspecified request.

[FeralFlora]

Why not just use the fenced_div syntax to use that filter?

For a few reasons:

1. Because I'm writing in an environment (Obsidian), where the gfm alert syntax is native. Preferably, I would use -f markdown+alerts, if that gets supported: Add the 'alert' extension to Pandoc standard markdown #9716
2. By using alerts, I'm specifically trying to avoid using fenced divs or some other syntax. I thought that was the reason why support for alerts was added?
3. Because I'm just testing that filter, I don't want to change my workflow for it.

---

The other question is what output -- again lets say I want PDF and choose Typst as the PDF engine then I want the syntax to match a Typst construct, not some generic title and emoji output.

Yes, I thought the Pandoc's conversion goal with alerts was to translate them into alerts / admonitions / callouts as appropriate for each writer. See @jgm's comment here:

I also wanted to make sure these alerts would translate well to other formats that support admonitions, e.g. rst, asciidoc, docbook.
jgm/commonmark-hs#132 (comment)

Some writers have already been adapted to accomodate this, when possible: #9475 (comment), #5690

so just asking for a filter is an underspecified request.

You are right. I'm mainly interested in PDF output, and I don't know which way of styling is most appropriate for that - nothing obvious, I suppose, which is why the filter is needed. But as you mention, it gets more complicated with the different PDF engines. As is, I just use pdflatex, but I've dabbled with the Typst engine. And I suppose I would need different filters for different output formats, for example, the pandoc-latex-admonitions would do for LaTeX output. Unless there some conditionals that can be used in filters to support more output formats?

Perhaps the filter I found is not the best starting point after all.

[iandol]

I just tweaked an older filter i had that parses fenced_divs to also parse the GFM alert syntax (couple of lines changed). My filter was mostly for ODT and Typst, also outputs to plain text:

--[[
	This takes fenced div syntax and converts it for typst / plain text 
	or ODT / DOCX (you need to add styles to your odt/docx template)
]]--

--lg = require("logging") -- inspection
--md = require("mobdebug") -- debugging
--md.start()

local alerts = pandoc.List({'note', 'tip', 'important', 'warning', 'caution'})
local pretypst = pandoc.List({'#info[', '#tip[','#memorize[','#warning[','#clue(title: "Caution", icon: "❓", accent-color: red)['})
local preplain = pandoc.List({"💡 Note ","🔦 Tip ","🤚 Important ","🚨 Warning ","❗ Caution "})

function Div(d)
	if alerts:includes(d.classes[1]) then
		alert,alertidx = alerts:find(d.classes[1])
		if d.c[1].classes == nil or d.c[1].classes:includes(alert) then
			c = d.content[1].content
		else
			c = d.content[2].content
		end

		-- TYPST
		if FORMAT:match 'typst' then
			s = "\n" .. pretypst[alertidx] .. pandoc.utils.stringify(c) .. "]\n"
			return pandoc.RawBlock('typst', s)
		-- PLAIN TEXT
		elseif FORMAT:match 'plain' then
			inlines = pandoc.List()
			inlines[1] = pandoc.Str(preplain[alertidx])
			inlines[2] = pandoc.Space()
			inlines:extend(c)
			d.content[1] = pandoc.HorizontalRule()
			d.content[2] = pandoc.Plain(inlines)
			d.content[3] = pandoc.HorizontalRule()
			d.attributes = {['custom-style'] = alert}
			return d
		-- EVERYTHING ELSE
		else 
			d.attributes = {['custom-style'] = alert} -- add custom-style for ODT/DOCX/ICML
			return d
		end
	end
end

pandoc -L admonitions.lua -f gfm+fenced_divs -t typst

> [!tip]
> Some text

::: {.tip}
Some Text
:::

::: {.warning}            
Some Text
:::

Generates this PDF output with Typst (you'll need the gentle-clues package):

Or plain text:

------------------------------------------------------------------------
🔦 Tip  Some text
------------------------------------------------------------------------

------------------------------------------------------------------------
🔦 Tip  Some Text
------------------------------------------------------------------------

------------------------------------------------------------------------
🚨 Warning  Some Text
------------------------------------------------------------------------

All filters will work in roughtly the same way. They trigger for each div in a document then check if the class matches a value like tip or warning, if so then you can switch the output depending on the output format. For GFM alerts Pandoc add a div containing a title and paragraph by default, I add custom-style but otherwise don't remove the title except for Typst or plain text... Typst is great for a lot of work (so much less hassle than LaTeX to tweak, only 10MB download, 50x faster to generate a PDF etc.), so you may be good to go with that route. For LaTeX you need to identify the styling environment then inject that markup with the filter and probably also modify the template to suit.

[FeralFlora]

@iandol Thanks so much for customizing and sharing this filter! To include the gentle-clues package, I suppose I need to add it to the default template, then specify the adapted template in my command?

Edit: Did the above, and it worked great:

[iandol]

You can customise the template, so for example this is what I have in my custom.typst template:

https://github.com/iandol/dotpandoc/blob/master/templates/custom.typst

BUT you could also use a defaults file and header-includes and inject it there, then no need for a custom template (note in my working files i don't inject the package as it is in my template but i do add some other tweaks via header-includes):

e.g. https://github.com/iandol/dotpandoc/blob/master/defaults/typst.yaml and https://github.com/iandol/dotpandoc/blob/master/metadata/typst-includes.yaml

Placed in the correct folders of your pandoc data directory and they are easy to call, and you can have different defaults files for different sets of features etc.

[FeralFlora]

Thanks for the inspiration, and the details.

I ran into an issue. I tried to add a custom title to see if it would work, but it seems like the filter does not support these. Both Obsidian and gentle-clues support these:

• Obsidian doc link: https://help.obsidian.md/Editing+and+formatting/Callouts#Change+the+title
• Gentle clues doc link: https://github.com/jomaway/typst-gentle-clues/blob/edbe54dace92ce1717b5aea2097d09e3a0184dc8/docs.typ#L65-L74

This is the custom title format in Obsidian:

> [!warning] Custom warning
> A warning

When rendered, it takes the place of the default "Warning" heading:

In gentle-clues, a custom title is specified like this:

      #example(title: "Custom title")[ Content ...]

And the gentle-clues behavior is the same:

So the Obsidian syntax and gentle-clues alert syntaxes have components that should be compatible.

Do you think this can be supported, even though GFM alerts don't have this syntax for custom titles?

Btw, I found a feature request to support basically the same syntax as used by Obsidian for custom alert titles in gfm:
https://github.com/orgs/community/discussions/103219
And these highly upvoted suggestions for the same in the original alert feature request thread: https://github.com/orgs/community/discussions/16925#discussioncomment-2787141
https://github.com/orgs/community/discussions/16925#discussioncomment-2794263

[FeralFlora]

This is the error I got:

error: unexpected argument: block
    ┌─ \\?\C:\Users\user\Desktop\toPD3B7.html:108:7
    │
108 │ #quote(block: true)[
    │        ^^^^^^^^^^^

help: error occurred in this call of function `clue`
   ┌─ @preview/gentle-clues:0.8.0\lib\predefined.typ:90:88
   │
90 │   #let quote(title: auto, icon: "assets/quote.svg", attribution: none, content, ..args) = clue(
   │ ╭─────────────────────────────────────────────────────────────────────────────────────────^
91 │ │   accent-color: eastern,
92 │ │   title: if-auto-then(title, get-title-for("quote")),
93 │ │   icon: icon,
   · │
96 │ │   #typst_quote(block: true, attribution: attribution)[#content]
97 │ │ ]
   │ ╰─^

Error producing PDF.

[iandol]

Pandoc does not parse the custom titles with the same output:

pandoc -f gfm -t native

> [!warning] Custom warning
> A warning

> [!warning]
> A warning

[ BlockQuote
    [ Para
        [ Str "[!warning]"
        , Space
        , Str "Custom"
        , Space
        , Str "warning"
        , SoftBreak
        , Str "A"
        , Space
        , Str "warning"
        ]
    ]
, Div
    ( "" , [ "warning" ] , [] )
    [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Warning" ] ]
    , Para [ Str "A" , Space , Str "warning" ]
    ]
]

So the filter would need to also do custom parsing of blockquotes. That is possible but I don't have time to do this soon, but the code will be pretty straightforward. You need to check if the first line starts with [!label] then extract out the rest of the content then write that to the gentle-clues syntax. I can highly recommend using mobdebug + zerobrane, a remote debugger that allows you to pause the filter, check each variable etc. to really understand what is going on. I never learnt Lua, but with a debugger you can peer under the hood and mostly get where you need to get...

[iandol]

@FeralFlora — I added a parser for custom titles in my filter, so this markdown:

> [!tip]
> GFM Alert.
> Some **Tip content**.
> More content: H~2~O.

> [!warning] A Custom title
> GFM Alert with custom title.
>
> My **warning** content.
> Some *more* content.

:::note
Fenced Div. 

Some note content. 
More *content*.
:::

::: {.important title="Custom Title"}
Some content.
:::

becomes this Typst:

ODT (you need a custom reference doc with styles added):

Plain text:

----------------------------------
🔦 Tip
GFM Alert. Some Tip content. More content: H₂O.
----------------------------------

----------------------------------
🚨 A Custom title
GFM Alert with custom title.

My warning content. Some more content.
----------------------------------

----------------------------------
💡 Note
Fenced Div.

Some note content. More content.
----------------------------------

----------------------------------
🤚 Custom Title
Some content.
----------------------------------

Filter: https://github.com/iandol/dotpandoc/blob/master/filters/alerts.lua

[FeralFlora]

Thanks so much for implementing this! It works great in my tests so far, converting to PDF via Typst :)

[iandol]

It could be easily extended to support LaTeX too, but I've mostly lost patience with LaTeX as Typst does most of what I need with an order of magnitude less complexity...