Goldmark Extension

The kazarimd package integrates Kazari into a Goldmark Markdown pipeline, replacing the default fenced code block renderer and adding :::code-group container support. All meta string features work automatically through the fence info string.

Import path: github.com/frostybee/kazari/goldmark

Install

go get github.com/frostybee/kazari/goldmark@latest

Fenced code blocks

Register kazarimd.New(engine) as a Goldmark extension to route all fenced code blocks through Kazari:

1
import (
2
    "github.com/frostybee/kazari"
3
    kazarimd "github.com/frostybee/kazari/goldmark"
4
    "github.com/yuin/goldmark"
5
)
6
7
md := goldmark.New(
8
    goldmark.WithExtensions(kazarimd.New(engine)),
9
)
10
11
var buf bytes.Buffer
12
if err := md.Convert([]byte(markdownSource), &buf); err != nil {
13
    log.Fatal(err)
14
}

The extension reads the fence info string (everything after the opening backticks), splits it into language and meta, and calls engine.RenderWithMeta(code, meta). The language is the first word; everything after the first space is the meta string.

1
```go title="main.go" {3-5} showLineNumbers

In this example, go is the language and title="main.go" {3-5} showLineNumbers is the meta string passed to the engine. All meta string features work automatically: title=, line markers, showLineNumbers, focus=, collapse, and the rest.

Code groups

Register kazarimd.CodeGroups(engine) to add :::code-group container support:

1
md := goldmark.New(
2
    goldmark.WithExtensions(
3
        kazarimd.New(engine),
4
        kazarimd.CodeGroups(engine),
5
    ),
6
)

CodeGroups(engine) calls engine.EnableCodeGroups() internally, which enables code group CSS and JS in the engine output. No separate setup step is needed.

Register CodeGroups(engine) during setup, before the engine is used for rendering. EnableCodeGroups() mutates the engine configuration without synchronization, so calling it concurrently with active Convert() calls is not safe.

Tab labels are derived in priority order: explicit title= meta attribute, then extracted filename comment from the first line of code, then capitalized language name, then "Code" as a fallback. See the Code Groups page for the full :::code-group syntax, tab behavior, sync= attribute, and keyboard navigation.

CSS and JS injection

CSS() and JS() are config-derived and idempotent. The output is the same regardless of which blocks were rendered. Call once per site build, not per page.

When CodeGroups(engine) is registered before engine.CSS() is called, the CSS output includes tab bar styles and the JS output includes the tab-switching and sync handler.

Inline assets

1
var buf bytes.Buffer
2
md.Convert(markdownSource, &buf)
3
4
fmt.Fprintf(w, "<style>%s</style>", engine.CSS())
5
// ... converted markdown output ...
6
fmt.Fprintf(w, "<script>%s</script>", engine.JS())

External files (SSG pattern)

Write assets to disk once during the build, then reference them from page templates:

1
os.WriteFile("assets/kazari.css", []byte(engine.CSS()), 0644)
2
os.WriteFile("assets/kazari.js", []byte(engine.JS()), 0644)

1
<link rel="stylesheet" href="/assets/kazari.css">
2
<script type="module" src="/assets/kazari.js"></script>

Hashed assets

engine.Assets() returns CSS and JS with content-hashed filenames for cache busting:

1
assets := engine.Assets()
2
os.WriteFile("assets/"+assets.CSS.Filename, []byte(assets.CSS.Content), 0644)
3
os.WriteFile("assets/"+assets.JS.Filename, []byte(assets.JS.Content), 0644)

Each AssetFile includes Content, Hash (8-char hex FNV-1a), and Filename (e.g., kazari-a1b2c3d4.css).

Full example

1
package main
2
3
import (
4
    "bytes"
5
    "context"
6
    "fmt"
7
    "log"
8
9
    "github.com/frostybee/kazari"
10
    kazarinuri "github.com/frostybee/kazari/nuri"
11
    kazarimd "github.com/frostybee/kazari/goldmark"
12
    "github.com/frostybee/nuri"
13
    "github.com/frostybee/nuri/bundle/core"
14
    "github.com/yuin/goldmark"
15
)
16
17
func main() {
18
    ctx := context.Background()
19
    hl, err := nuri.New(ctx, nuri.WithFS(core.FS()))
20
    if err != nil {
21
        log.Fatal(err)
22
    }
23
    defer hl.Close(ctx)
24
25
    engine := kazari.New(
26
        kazari.WithHighlighter(kazarinuri.New(ctx, hl)),
27
        kazari.WithThemes("github-light", "github-dark"),
28
        kazari.WithCopyButton(true),
29
    )
30
31
    md := goldmark.New(
32
        goldmark.WithExtensions(
33
            kazarimd.New(engine),
34
            kazarimd.CodeGroups(engine),
35
        ),
36
    )
37
38
    src := []byte("# Hello\n\n```go title=\"main.go\"\nfmt.Println(\"hello\")\n```\n")
39
    var buf bytes.Buffer
40
    if err := md.Convert(src, &buf); err != nil {
41
        log.Fatal(err)
42
    }
43
44
    fmt.Printf("<html><head><style>%s</style></head><body>%s<script>%s</script></body></html>",
45
        engine.CSS(), buf.String(), engine.JS())
46
}

Single engine pattern

When using the Goldmark extension alongside direct engine.Render() or engine.RenderWithMeta() calls, use a single engine instance for everything. Each engine produces its own CSS and JS output. Including output from two separate engines in the same page causes duplicate function declarations.

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithThemes("github-light", "github-dark"),
4
)
5
6
md := goldmark.New(goldmark.WithExtensions(
7
    kazarimd.New(engine),
8
    kazarimd.CodeGroups(engine),
9
))
10
var buf bytes.Buffer
11
md.Convert(markdownSource, &buf)
12
13
customBlock, _ := engine.Render(code, kazari.Options{Lang: "go", Title: "example.go"})
14
15
css := engine.CSS()
16
js := engine.JS()

One engine.CSS() and engine.JS() call covers both the Goldmark-rendered blocks and the directly rendered blocks.

Edge cases