goldmark-figure

goldmark-figure is a goldmark extension to parse markdown paragraphs that start with an image into HTML <figure> elements. One nice thing is it doesn't use any new markdown syntaxes.

Example markdown source:

![Picture of Oscar.](/path/to/cat.jpg)
Awesome caption about **Oscar** the kitty.

Render result:

<figure>
<img src="/path/to/cat.jpg" alt="Picture of Oscar." />
<figcaption><p>Awesome caption about <strong>Oscar</strong> the kitty.</p></figcaption>
</figure>

Multiple images are supported:

![Picture of Oscar.](/path/to/cat1.jpg)
![Picture of Luna.](/path/to/cat2.jpg)
Awesome captions about the **kitties**.

<figure>
<img src="/path/to/cat1.jpg" alt="Picture of Oscar.">
<img src="/path/to/cat2.jpg" alt="Picture of Luna.">
<figcaption><p>Awesome captions about the <strong>kitties</strong>.</p></figcaption>
</figure>

Why?

Using dedicated <figure> and <figcaption> elements makes styling images with descriptions much easier. Here is an example:

I hear they are also good for SEO.

Installation

go get github.com/mangoumbrella/goldmark-figure

Usage

import (
    "bytes"
    "fmt"

    "github.com/mangoumbrella/goldmark-figure"
    "github.com/yuin/goldmark"
)

func main() {
    markdown := goldmark.New(
        goldmark.WithExtensions(
            figure.Figure,
        ),
    )
    source := `
    ![Picture of Oscar.](/path/to/cat.jpg)
    Awesome caption about **Oscar** the kitty.
    `
    var buf bytes.Buffer
    if err := markdown.Convert([]byte(source), &buf); err != nil {
        panic(err)
    }
    fmt.Print(buf.String())
}

Option to add link to the image

Example:

goldmark.WithExtensions(
    figure.Figure.WithImageLink(),
),

Render result:

<figure>
<a href="/path/to/cat.jpg">
<img src="/path/to/cat.jpg" alt="Picture of Oscar." />
</a>
<figcaption>Awesome caption about <strong>Oscar</strong> the kitty.</figcaption>
</figure>

See figure_test.go for more examples.

Changelog

v1.2.0 (2024-06-19)

• Support multiple images (see #5).

v1.1.0 (2024-06-18)

• New option to add a link to the image when rendering the figure (see #4).

LICENSE

MIT

Authors

Yilei Yang