Filters

The ssglib.filters module provides Pandoc filter functions for processing Obsidian vault content. Filters are passed to doc:walk() to transform a Pandoc document.

local filters = require "ssglib.filters"

callout_filter

A filter function for BlockQuote elements. Converts Obsidian callout syntax into Pandoc Div or Figure elements.

Standard callouts become a Div with classes callout and callout-<marker>:

> [!warning] This is important.

Figure callouts become a Figure element with caption:

> [!figure] ![[photo.jpg]]
> A photo caption.

Usage:

local filter = { BlockQuote = filters.callout_filter }
doc = doc:walk(filter)

make_base_filter(vault, source, render_base)

Create a Para filter that detects paragraphs containing a lone image embed pointing to a .base file and replaces the entire paragraph with the block returned by render_base(resolved_path).

local filter = {
  Para = filters.make_base_filter(vault, note, function(path)
    return render_base(path)
  end),
}
doc = doc:walk(filter)

make_image_filter(vault, site, source)

Create an Image filter that copies images from the vault to the site and generates responsive srcset attributes. The filter creates multiple resized versions of each image. Image dimensions are cached in sidecar .meta files next to the output images.

local filter = { Image = filters.make_image_filter(vault, site, note) }
doc = doc:walk(filter)

This filter requires GraphicsMagick (gm convert) for image resizing.

make_link_filter(vault, source)

Create a Link filter that resolves vault wikilinks to URLs. Links to files not found in the vault are left unchanged.

local filter = { Link = filters.make_link_filter(vault, note) }
doc = doc:walk(filter)

Given a vault note Hello World.md with permalink: hello/, a wikilink [[Hello World]] becomes a link to /hello/.

make_codeblock_filter(env, ...)

Create a CodeBlock filter that executes code blocks with the eval class. The code is run in the provided environment table and the return value replaces the code block in the document.

local filter = {
  CodeBlock = filters.make_codeblock_filter(overlay(_G, {
    contents = function() return build_contents_list() end,
  })),
}
doc = doc:walk(filter)

In a markdown file, an evaluated code block looks like this:

```eval
contents()
```

The expression is evaluated and its return value (typically a Pandoc AST element) replaces the code block. If evaluation fails, the error message is shown in a code block.