Post-Render Callbacks

Post-render callbacks run after each code block is rendered, receiving the HTML string and a BlockInfo struct with metadata about the block. They enable HTML modifications that built-in features and CSS cannot achieve: injecting new elements, wrapping blocks in custom containers, or adding attributes based on block context.

Basic callback

Register a callback with WithPostRender. This example wraps every titled block in a <figure> with a <figcaption>:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithPostRender(func(html string, info kazari.BlockInfo) string {
4
        if info.Title == "" {
5
            return html
6
        }
7
        return fmt.Sprintf(
8
            "<figure>%s<figcaption>%s</figcaption></figure>",
9
            html, info.Title,
10
        )
11
    }),
12
)

→ Blocks with a title render inside a <figure> element. Blocks without a title pass through unchanged.

The callback receives the complete HTML of the rendered .kazari-block div. Return the modified string. Return the input unchanged to skip modification.

TODO/FIXME badges

Inject badge elements next to comment annotations. This is distinct from regex markers, which style existing text but cannot insert new HTML:

1
todoRe := regexp.MustCompile(`(>[^<]*?)(TODO:)`)
2
fixmeRe := regexp.MustCompile(`(>[^<]*?)(FIXME:)`)
3
4
engine := kazari.New(
5
    kazari.WithHighlighter(hl),
6
    kazari.WithPostRender(func(html string, info kazari.BlockInfo) string {
7
        html = todoRe.ReplaceAllString(html,
8
            `${1}<span class="kz-todo-badge">TODO</span> `)
9
        html = fixmeRe.ReplaceAllString(html,
10
            `${1}<span class="kz-fixme-badge">FIXME</span> `)
11
        return html
12
    }),
13
)

→ TODO: and FIXME: in comments are replaced with styled badge spans. The regex pattern (>[^<]*?) targets only visible text content, not attribute values like data-code.

Style the badges with CSS in the consumer's stylesheet:

1
.kz-todo-badge {
2
    display: inline-block;
3
    font-size: 0.7em;
4
    font-weight: 700;
5
    padding: 0.1em 0.45em;
6
    border-radius: 3px;
7
    background: rgba(234, 179, 8, 0.2);
8
    color: #b45309;
9
}
10
.kz-fixme-badge {
11
    display: inline-block;
12
    font-size: 0.7em;
13
    font-weight: 700;
14
    padding: 0.1em 0.45em;
15
    border-radius: 3px;
16
    background: rgba(239, 68, 68, 0.2);
17
    color: #dc2626;
18
}

BlockInfo fields

Every callback receives a BlockInfo struct with metadata about the rendered block:

Use BlockInfo fields to conditionally apply modifications:

1
kazari.WithPostRender(func(html string, info kazari.BlockInfo) string {
2
    if info.Lang != "go" {
3
        return html
4
    }
5
    return html + `<a class="playground-link" href="#">Run in Playground</a>`
6
})

→ A playground link appears below Go blocks only. Other languages pass through unchanged.

Multiple callbacks

Call WithPostRender multiple times to register multiple callbacks. They run in registration order, each receiving the output of the previous one:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithPostRender(addFigCaption),
4
    kazari.WithPostRender(addTodoBadges),
5
)

→ addFigCaption runs first, then addTodoBadges receives the already-wrapped HTML. The same BlockInfo is passed to every callback in the chain.

Configuration

Post-render callbacks are Go API only. They cannot be configured via meta strings or config files.

Mermaid pass-through blocks bypass post-render callbacks. They return a bare <pre class="mermaid"> element before the post-render step runs.

Post-render callbacks execute at the very end of the render pipeline, after RenderBlock assembles the full HTML string.

Related

• Custom Highlighters for swapping tokenization engines or accessing raw tokens
• Client-Side Extensibility for extending blocks with CSS and JavaScript instead of Go callbacks