Skip to content

Latest commit

 

History

History
108 lines (83 loc) · 3.28 KB

README.md

File metadata and controls

108 lines (83 loc) · 3.28 KB
Raw

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.

dir := "/path/to/parent"

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