Lua filters for Pandoc to generate LaTeX (thus PDF) color boxes from Obsidian style callouts and enable imeages embeds (wikilink style). The two filters are:
Please refer to Pandoc online manual (PDF manual) to learn more about its use. Lua filters are described in the Lua filters page from Pandoc's website.
The Lua filters can be used by invoking pandoc via command line (unix shell):
pandoc --lua-filter=obsidian_filter.lua -L=bang_wikilink.lua [...]or via the Pandoc defaults key:
filters:
- obsidian_callouts.lua
- bang_wikilink.luaPandoc defaults are a useful configuration file to invoke Pandoc
An example similiar to what I would use is pandoc_defaults_obsdian2latex.yaml. In particular:
from: gfm+wikilinks_title_after_pipe
filters:
- ${.}/obsidian_filter.lua
- ${.}/bang_wikilink.lua
pdf-engine-opt: "--shell-escape"
I personally use a GNU/Linux operating system, thus I will post only unix like commands and conventions, I am sorry for any Windows user.
By using Pandoc to generate a PDF documents, you will need a local TeX distribution such as TeX Live.
For now, the Lucide icons are SVG files, thus Inkscape is required in order to convert the SVG icons (the conversion is done during LaTeX compilation). Furthermore, you will need to invoke pandoc with the --pdf-engine-opt="--shell-escape" (for TeX Live) to allow LaTeX to do shell escaping. Please take a look at the svg package manual (page 3) for more information on the shell escaping and Inkscape requirement. I am willing to remove the SVG files by statically converting them once, in order to remove all these requirements (referring to Inkscape and shell-escape option requirements).
The icons are taken from Lucide, the default icon set used by Obsidian. I downloaded the ones I need for my setup in white color (color can be customized in the web page) into the lucide_personal directory, appending a _white suffix to each one. The downloaded icons are the one used by Obsidian plus some icons used for my custom callouts.
All the default Obsidian callouts are implemented. Their look is different, since they are implemented in LaTeX via the tcolorbox package.
Note
I am aware of the Pandoc support for GitHub flavoured Markdown (gfm), which has its implementation of callouts (which I am using right now! ironic), called alerts. However, these gfm alerts differ significantly from the Obsidian style callouts:
- they do not support custom titles (e.g.
> [!NOTE] Note titlewill not work at all, while> [!NOTE]will always display Note as the title); - they are not extensible (like adding custom callouts), nor editable in any form;
- (some) colors and (some) icons of the 5 existings gfm alerts differ from the Obsidian style callouts (e.g. the
[!WARNING]alert). Thus I developed this filter to enable the use of Obsidian style callouts with the power of Pandoc conversion to other formats.
Caution
Title only callouts are functional but they are treated the same as callouts with content: they will generate a tcolorbox with empty content, leading to a white content space below the title. This can be improved by designing a better tcolorbox in LaTeX which does not leave an empty white space beneath the title only callout.
| Color | RGB |
|---|---|
| red | 251, 70, 76 |
| blue | 2, 122, 255 |
| cyan | 83, 223, 221 |
| orange | 233, 151, 110 |
| green | 68, 207, 110 |
| purple | 168, 130, 225 |
| gray | 158, 157, 158 |
| yellow | 176, 187, 0 |
All the color but for yellow are from Obsidian: the yellow color is custom since there is no yellow callout in Obsidian by default.
Based on my use of Obsidian (and consequentely Quartz and Pandoc), I created few custom callouts. Particularly:
IMAGE, lucide iconimage, color blueGRAPH, lucide iconchart-line, color cyanSCHEMATIC, lucide iconcircuit-board, color yellow (I could change its name toCIRCUITin the future)
Another required filter was a simple filter to currectly process the Obsidian style assets (similiar to wikilinks) with a ! in front. For instance:
![[image.png]]The bang_wikilink.lua makes this conversion after the reading phase, so at a abstract syntax tree or AST level (see Pandoc's manual).
This structure [[wikilink|alternate text]] is already currectly handled by Pandoc if the wikilinks_title_after_pipe extension is added to gfm (e.g. pandoc --from gfm+wikilinks_title_after_pipe), and so they do not require any custom filtering.
Warning
This filter can potentially break embeddings of other kind of file. In the future I could add a better filtering to look for images file extensions.
Pull requests, bug reports, and feature requests are welcome. Please feel free to contact me and contribute to this project if you want to! The code is not perfect, but hopefully clear enough.
The Lucide icon set is licensed under the ISC License.
Pandoc is free software, released under the GPL. Copyright 2006–2025 John MacFarlane.
Lua is free software distributed under the terms of the MIT license.
The base of the obsidian_filter.lua is this Lua script from iandol's dotfiles repository, licensed under the MIT License. He was using Typst for his personal Lua filter, but I wanted to use LaTeX. Thanks!
Also my friends TheICSDI and mttcrn helped me out during the writing of the scripts. Thank you!
See LICENSE.