img64

README

goldmark-img64

Overview

goldmark-img64 is a plugin for goldmark that automatically embeds image files as Base64-encoded data directly into rendered HTML. This is especially useful for scenarios where:

• Hosting external image files is not practical.
• You need a single self-contained HTML file.

For example, the following Markdown image will be embedded as Base64 data:

![alt](./image.png "title")

<p><img src="data:image/png;base64,..." alt="alt" title="title"></p>

This package supports these image types.

• "image/apng"
• "image/avif"
• "image/gif"
• "image/jpeg"
• "image/png"
• "image/svg+xml"
• "image/webp"

Installation

go get github.com/tenkoh/goldmark-img64

Limitations

By default, only images that satisfy all the following conditions will be embedded as Base64-encoded data. Other images will have their file paths included as-is in the output.

Conditions

• Stored locally: The image file must reside on the local file system.
• Valid path: The image path must be:
  • A relative path based on the executable's directory, or
  • An absolute path.

Notes

• Remote image URLs (e.g., https://example.com/image.png) are not supported by default. See Embedding Remote Images for how to handle such cases.

Usage recipes

Here are various ways to use goldmark-img64:

1. Basic Usage
2. Handling Non-Standard Paths
3. Embedding Remote Images
4. Combining PathResolver and FileReader

Basic Usage

The following example demonstrates how to use goldmark-img64 with its default settings to convert a Markdown file (target.md) into HTML with embedded Base64-encoded images.

package main

import (
    "io"
    "os"

    "github.com/yuin/goldmark"
    img64 "github.com/tenkoh/goldmark-img64"
)

func main() {
    b, _ := os.ReadFile("target.md")
    goldmark.New(goldmark.WithExtensions(img64.Img64)).Convert(b, os.Stdout)
}

Handling Non-Standard Paths

When your target markdown is not in the current working directory, try WithPathResolver option. You can change paths as you like.

PathResolver is just a function func(path string) string. This repository now provides a simple implementation: ParentLocalPathResolver, which adds parent directory's path.

goldmark.New(
    goldmark.WithExtensions(img64.Img64),
    goldmark.WithRendererOptions(
        img64.WithPathResolver(img64.ParentLocalPathResolver(dir)),
    ),
)

Embedding Remote Images

When you want to embed non local images (ex. https://..../sample.png) or want to add pre/post process, you can customize FileReader.

FileReader is just a function func(path string) ([]byte, error). This repository provides an example: AllowRemoteFileReader, which allows embed online images.

goldmark.New(
    goldmark.WithExtensions(img64.Img64),
    goldmark.WithRendererOptions(
        img64.WithFileReader(img64.AllowRemoteFileReader(http.DefaultClient)),
    ),
)

Combining PathResolver and FileReader

You can use both WithPathResolver and WithFileReader at the same time.

License

MIT

Author

tenkoh

Documentation

Index

• Variables
• func NewImg64(opts ...Img64Option) *img64
• func NewImg64Renderer(opts ...Img64Option) *img64Renderer
• func WithFileReader(r FileReader) interface{ ... }
• func WithPathResolver(r PathResolver) interface{ ... }
• type FileReader
  • func AllowRemoteFileReader(client *http.Client) FileReader
  • func DefaultFileReader() FileReader
• type Img64Config
  • func (c *Img64Config) SetOption(name renderer.OptionName, value any)
• type Img64Option
• type PathResolver
  • func DefaultPathResolver() PathResolver
  • func ParentLocalPathResolver(parentPath string) PathResolver

Variables

var Img64 = &img64{}

Img64 is an implementation of goldmark.Extender

Functions

func NewImg64

func NewImg64(opts ...Img64Option) *img64

NewImg64 initializes Img64: goldmark's extension with its options. Using default Img64 with goldmark.WithRenderOptions(opts) give the same result.

func NewImg64Renderer

func NewImg64Renderer(opts ...Img64Option) *img64Renderer

func WithFileReader

func WithFileReader(r FileReader) interface {
	renderer.Option
	Img64Option
}

WithFileReader changes reading image attribute from default. For example, it allows reading online images. (it is disabled in default reader)

func WithPathResolver

func WithPathResolver(r PathResolver) interface {
	renderer.Option
	Img64Option
}

WithPathResolver adds custom behavior to read image source path. For example, relative paths could be converted into absolute paths by adding the parent directory path.

Types

type FileReader

type FileReader func(path string) ([]byte, error)

func AllowRemoteFileReader

func AllowRemoteFileReader(client *http.Client) FileReader

AllowRemoteFileReader enables embedding remote images which is prohibited with default reader. Use this only if all images are confirmed to be safe. This is one example of FileReader implementations.

func DefaultFileReader

func DefaultFileReader() FileReader

type Img64Config

type Img64Config struct {
	html.Config
	PathResolver PathResolver
	FileReader   FileReader
}

Img64Config embeds html.Config to refer to some fields like unsafe and xhtml.

func (*Img64Config) SetOption

func (c *Img64Config) SetOption(name renderer.OptionName, value any)

SetOption implements renderer.NodeRenderer.SetOption

type Img64Option

type Img64Option interface {
	renderer.Option
	SetImg64Option(*Img64Config)
}

type PathResolver

type PathResolver func(string) string

func DefaultPathResolver

func DefaultPathResolver() PathResolver

func ParentLocalPathResolver

func ParentLocalPathResolver(parentPath string) PathResolver

ParentLocalPathResolver adds parent directory path (ex. /var + target.md = /var/target.md). This is one example of PathResolver implementations.