Goldmark Integration

If the application renders Markdown (a blog, a wiki, a documentation site), the Goldmark extension lets content authors embed icons inline with :icon[prefix:name] syntax, with no Go code in the templates and no manual SVG markup.

Install

The Goldmark extension is in a separate submodule:

go get github.com/frostybee/go-swarm-icons/goldmark@latest

This module depends on the core module and github.com/yuin/goldmark.

Register the extension

Create an IconManager, then pass it to the extension when configuring Goldmark:

1
import (
2
    "bytes"
3
    "fmt"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
    swarmgoldmark "github.com/frostybee/go-swarm-icons/goldmark"
7
    "github.com/frostybee/go-swarm-icons/lucide"
8
    "github.com/yuin/goldmark"
9
)
10
11
func main() {
12
    manager := swarmicons.Default("lucide", lucide.Provider())
13
14
    ext := &swarmgoldmark.Extension{
15
        Manager:         manager,
16
        SilentOnMissing: true,
17
    }
18
    md := goldmark.New(goldmark.WithExtensions(ext))
19
20
    input := []byte("Click the :icon[lucide:home] icon to go home.")
21
    var buf bytes.Buffer
22
    if err := md.Convert(input, &buf); err != nil {
23
        panic(err)
24
    }
25
    fmt.Println(buf.String())
26
}

Inline syntax

The parser recognizes the pattern :icon[...] in Markdown source text. Everything between the brackets is parsed as an icon name followed by optional attributes.

Basic usage

1
:icon[lucide:home]

Bare name (default prefix)

If the manager has a default prefix set, the prefix can be omitted:

1
:icon[home]

This resolves as manager.Get("home"), which uses the default prefix.

With attributes

Attributes follow the icon name, separated by spaces. Values can be double-quoted, single-quoted, or unquoted:

1
:icon[lucide:star size="24" class="gold"]
2
:icon[lucide:star size='24' class='gold']
3
:icon[lucide:star size=24]

Multiple icons on one line

1
:icon[lucide:home] and :icon[lucide:star]

Both icons render independently.

Transform vs. pass-through attributes

Attributes split into two groups based on the key name:

Transform attributes

These are applied via fluent Icon methods after the icon is resolved:

Attribute	Fluent method	Example
`size`	`icon.Size(int)`	`size="24"`
`rotate`	`icon.Rotate(float64)`	`rotate="45"`
`flip`	`icon.Flip(string)`	`flip="h"`
`opacity`	`icon.Opacity(float64)`	`opacity="0.5"`
`title`	`icon.Title(string)`	`title="Home"`

Transforms are applied in this order: size, rotate, flip, opacity, title.

Pass-through attributes

All other attributes (class, id, width, data-*, etc.) are passed to manager.Get() as caller-level attributes (layer 5 in the attribute merge). They follow the same merge rules as any other caller attributes.

1
:icon[lucide:home class="icon-blue" id="nav-home"]

Missing icons

`SilentOnMissing: true`

When an icon is not found, the extension renders an HTML comment instead of returning an error:

1
<!-- SwarmIcons: Icon "lucide:missing" not found -->

The rest of the Markdown document continues to render normally.

`SilentOnMissing: false` (default)

Full example

1
import (
2
    "bytes"
3
    "fmt"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
    swarmgoldmark "github.com/frostybee/go-swarm-icons/goldmark"
7
    "github.com/frostybee/go-swarm-icons/lucide"
8
    "github.com/yuin/goldmark"
9
)
10
11
func main() {
12
    manager, _ := swarmicons.NewConfig().
13
        AddProvider("lucide", lucide.Provider()).
14
        DefaultPrefix("lucide").
15
        DefaultAttributes(map[string]string{
16
            "stroke":       "currentColor",
17
            "stroke-width": "2",
18
            "fill":         "none",
19
        }).
20
        Build()
21
22
    ext := &swarmgoldmark.Extension{
23
        Manager:         manager,
24
        SilentOnMissing: true,
25
    }
26
    md := goldmark.New(goldmark.WithExtensions(ext))
27
28
    input := []byte(`# Welcome
29
30
Click :icon[home] to return.
31
32
Rate this: :icon[star size="16" class="gold" rotate="45"]
33
`)
34
35
    var buf bytes.Buffer
36
    if err := md.Convert(input, &buf); err != nil {
37
        panic(err)
38
    }
39
    fmt.Println(buf.String())
40
}

The output contains the <h1> heading, paragraph text with the inline <svg> for "home", and a second paragraph with a rotated, gold-classed star icon.