callout2latex.lua is a Pandoc Lua filter for converting GitHub, Typora, Obsidian, and Microsoft¹ styled Markdown Callout Blocks (also known as Alert Blocks, Message Boxes, or Admonitions²) into \LaTeX\ environments.

The basic functionality of this script has been implemented correctly, although some issues still remain, which I plan to address in future updates.

Most of this script was generated with the assistance of ChatGPT and DeepSeek, with minor modifications made by me.

Comparing with the pandoc-latex-admonition, which is a pandoc filter which allows you to add markdown admonitions to divs or codeblocks elements, this script has the following different features:

1. Use a more common syntax of admonition (Instead of using pandoc native Div), which is more commonly supported by different platforms and editors, and no additional syntax is introduced.
2. No matter what the admonition name is specified to be, this script always simply just pass the admonition type name to the the \LaTeX\ environment name intactly, which provides users with maximized freedom.
3. Lightweight (just one Lua script), simple and easy to use.

To use this filter script, specify it as a Lua filter for Pandoc using the --lua-filter flag. Examples of conversion commands are provided in command.sh and command.ps1.

pandoc file.md --output file.pdf --lua-filter callout2latex.lua

If your Markdown file contains the following:

A note callout block with a title:

> [!note] This is the note title
> This is a line of info.

A note callout block without a title:

> [!note]
> This is a line of info
> It may contain multiple lines,
> 
> Or even a new paragraph. 

It will be converted to \LaTeX\ as:

A note callout block with a title:

\begin{note}[This is the note title]

This is a line of info.

\end{note}

A note callout block without a title:

\begin{note}

This is a line of info

It may contain multiple lines,

Or even a new paragraph.

\end{note}

Here are a few things to note about this filter script³:

> [!NOTE]
> Notice the two spaces after the `[!NOTE]` label.

\begin{note}[Notice the two spaces after the `[!NOTE]` label. ]
\end{note}

Currently, ordered lists (enumerate) and unordered lists (itemize) are not supported within callout blocks.

To install callout2latex.lua and make it accessible globally on localhost, follow these steps:

Pandoc stores user-specific data, including filters, in its user data directory. To find the directory, you should firstly run the following command in your terminal or command prompt:

pandoc --version

Then Look for the line that shows User data directory:, which might look something like:

User data directory: /home/username/.pandoc

On different systems, the typical paths are:

• Linux: ~/.pandoc/
• macOS: ~/Library/Application Support/pandoc/
• Windows: C:\Users\username\AppData\Roaming\pandoc\

If the directory does not exist, create it manually.

Inside the user data directory, locate or create a filters subdirectory (~/.pandoc/finters as an example):

mkdir -p ~/.pandoc/filters

Copy callout2latex.lua to the filters directory:

cp callout2latex.lua ~/.pandoc/filters/

To ensure the filter is correctly installed, run:

ls ~/.pandoc/filters/

You should see callout2latex.lua in the list.

After installation, you can apply the filter from any directory by running:

pandoc file.md --output file.pdf --lua-filter callout2latex.lua

Or, simply refer to the filter from the user data directory without specifying the full path:

pandoc file.md --output file.pdf --lua-filter callout2latex.lua

To simplify usage, you can create a shell alias:

echo 'alias callout2latex="pandoc --lua-filter=$HOME/.pandoc/filters/callout2latex.lua"' >> ~/.bashrc
source ~/.bashrc

Now you can use:

callout2latex file.md -o file.pdf

Consider the following Markdown syntax:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

After running pandoc with the Lua filter, the above blocks will be converted into \LaTeX\ environments. (Ensure the required environments are defined in your document class⁴. See example.cls for their definitions.)

This script supports custom \LaTeX\ environments. For example⁵, if you've defined definition and theorem environments correctly in your document class, you can use the following syntax:

[!definition] Left Coset Let $H$ be a subgroup of a group~$G$. A left coset of $H$ in $G$ is a subset of $G$ that is of the form $xH$, where $x \in G$ and $xH = { xh : h \in H }$. Similarly, a right coset of $H$ in $G$ is a subset of $G$ that is of the form $Hx$, where $Hx = { hx : h \in H }$

[!theorem] Lagrange's Theorem Let $G$ be a finite group, and let $H$ be a subgroup of $G$. Then the order of $H$ divides the order of $G$.

See README.pdf for the formatted Theorem of the \LaTeX\ output.

This project is licensed under the MIT License. See the LICENSE file for details.