Resolve relative image paths to file:// URLs in rendered HTML

README.md

@@ -58,6 +58,10 @@ make
 sudo install mdp /usr/local/bin/
 ```
 
+## Images
+
+`mdp` rewrites relative image paths into `file://` URLs based on the directory of the markdown file, so the browser can show images next to the markdown without copying them. This works for both `![alt](path)` and raw `<img>` tags (with `unsafe: true`). URLs that already have a scheme, such as `https://` or `data:`, are not changed.
+
 ## Configuration
 
 Configuration file is loaded from the following locations in order of priority:

e2e/run.sh

@@ -75,12 +75,16 @@ EOF
         continue
     fi
 
-    if diff -q "$expected_file" "$generated_file" > /dev/null 2>&1; then
+    # Expected html uses placeholders for the directories in file:// image URLs
+    resolved_expected_file="$test_dir/expected.html"
+    sed -e "s|__TESTDATA_DIR__|$TESTDATA_DIR|g" -e "s|__E2E_DIR__|$SCRIPT_DIR|g" "$expected_file" > "$resolved_expected_file"
+
+    if diff -q "$resolved_expected_file" "$generated_file" > /dev/null 2>&1; then
         echo "PASS: $name"
     else
         echo "FAIL: $name (content mismatch)"
         echo "--- Expected ---"
-        cat "$expected_file"
+        cat "$resolved_expected_file"
         echo "--- Actual ---"
         cat "$generated_file"
         echo "----------------"

e2e/testdata/image.config.yaml

@@ -0,0 +1 @@
+unsafe: true

e2e/testdata/image.html

@@ -0,0 +1,5 @@
+<h1>Image Test</h1>
+<p><img src="file://__TESTDATA_DIR__/images/a.png" alt="relative"></p>
+<p><img src="file://__E2E_DIR__/shared/b.png" alt="parent"></p>
+<p><img src="https://example.com/c.png" alt="absolute"></p>
+<img src="file://__TESTDATA_DIR__/d.png" width="300">

e2e/testdata/image.md

@@ -0,0 +1,9 @@
+# Image Test
+
+![relative](images/a.png)
+
+![parent](../shared/b.png)
+
+![absolute](https://example.com/c.png)
+
+<img src="d.png" width="300">

go.mod

@@ -8,9 +8,10 @@ require (
 	github.com/fsnotify/fsnotify v1.10.1
 	github.com/yuin/goldmark v1.8.5
 	github.com/yuin/goldmark-meta v1.1.0
+	golang.org/x/net v0.58.0
 )
 
 require (
-	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
 	gopkg.in/yaml.v2 v2.3.0 // indirect
 )

go.sum

@@ -4,8 +4,10 @@ github.com/yuin/goldmark v1.8.5 h1:r6N5afV5qj/5S4UTch8agZHJ8UxNCMwX7WjkkJam2NA=
 github.com/yuin/goldmark v1.8.5/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 github.com/yuin/goldmark-meta v1.1.0 h1:pWw+JLHGZe8Rk0EGsMVssiNb/AaPMHfSRszZeUeiOUc=
 github.com/yuin/goldmark-meta v1.1.0/go.mod h1:U4spWENafuA7Zyg+Lj5RqK/MF+ovMYtBvXi1lBb2VP0=
-golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
-golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU=

internal/cli/cli.go

@@ -107,7 +107,7 @@ func (c *cli) convert(filePath string, r *renderer.Renderer, w *output.Writer) (
 	}
 
 	// Render markdown to HTML
-	html, err := r.Render(markdown)
+	html, err := r.Render(markdown, filepath.Dir(filePath))
 	if err != nil {
 		return "", fmt.Errorf("failed to render: %w", err)
 	}

internal/renderer/image.go

@@ -0,0 +1,90 @@
+package renderer
+
+import (
+	"bytes"
+	"net/url"
+	"strings"
+
+	"golang.org/x/net/html"
+)
+
+// resolveImageSources rewrites the src attribute of every <img> in the
+// rendered HTML. A src without a scheme becomes a file:// URL under baseDir.
+// Every other token is copied through unchanged.
+func resolveImageSources(rendered []byte, baseDir string) []byte {
+	var out bytes.Buffer
+	z := html.NewTokenizer(bytes.NewReader(rendered))
+
+	for {
+		tt := z.Next()
+		if tt == html.ErrorToken {
+			// io.EOF is the only error a byte reader can produce
+			out.Write(z.Raw())
+			return out.Bytes()
+		}
+
+		if tt != html.StartTagToken && tt != html.SelfClosingTagToken {
+			out.Write(z.Raw())
+			continue
+		}
+
+		raw := z.Raw()
+		token := z.Token()
+		if token.Data != "img" {
+			out.Write(raw)
+			continue
+		}
+
+		changed := false
+		for i, attr := range token.Attr {
+			if attr.Key != "src" {
+				continue
+			}
+			resolved, ok := resolveImageSource(attr.Val, baseDir)
+			if ok {
+				token.Attr[i].Val = resolved
+				changed = true
+			}
+		}
+
+		if !changed {
+			out.Write(raw)
+			continue
+		}
+		writeTag(&out, token, tt == html.SelfClosingTagToken)
+	}
+}
+
+// resolveImageSource returns the src resolved against baseDir as a file:// URL.
+// It reports false when src should stay as is: empty, unparsable, or
+// already having a scheme or host.
+func resolveImageSource(src, baseDir string) (string, bool) {
+	// Browsers strip surrounding whitespace before resolving the URL
+	src = strings.TrimSpace(src)
+	if src == "" {
+		return src, false
+	}
+	ref, err := url.Parse(src)
+	if err != nil || ref.Scheme != "" || ref.Host != "" {
+		return src, false
+	}
+	base := &url.URL{Scheme: "file", Path: strings.TrimSuffix(baseDir, "/") + "/"}
+	return base.ResolveReference(ref).String(), true
+}
+
+func writeTag(out *bytes.Buffer, token html.Token, selfClosing bool) {
+	out.WriteString("<")
+	out.WriteString(token.Data)
+	for _, attr := range token.Attr {
+		out.WriteString(" ")
+		out.WriteString(attr.Key)
+		out.WriteString(`="`)
+		out.WriteString(html.EscapeString(attr.Val))
+		out.WriteString(`"`)
+	}
+	if selfClosing {
+		out.WriteString(" />")
+		return
+	}
+	out.WriteString(">")
+}

internal/renderer/image_test.go

@@ -0,0 +1,143 @@
+package renderer
+
+import (
+	"testing"
+)
+
+func TestResolveImageSources(t *testing.T) {
+	const baseDir = "/Users/you/docs"
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "resolves relative path",
+			in:   `<p><img src="images/a.png" alt="a"></p>`,
+			want: `<p><img src="file:///Users/you/docs/images/a.png" alt="a"></p>`,
+		},
+		{
+			name: "resolves dot-slash path",
+			in:   `<img src="./a.png" alt="">`,
+			want: `<img src="file:///Users/you/docs/a.png" alt="">`,
+		},
+		{
+			name: "resolves parent directory reference",
+			in:   `<img src="../shared/a.png" alt="">`,
+			want: `<img src="file:///Users/you/shared/a.png" alt="">`,
+		},
+		{
+			name: "resolves root-relative path",
+			in:   `<img src="/tmp/a.png" alt="">`,
+			want: `<img src="file:///tmp/a.png" alt="">`,
+		},
+		{
+			name: "keeps percent-encoded characters",
+			in:   `<img src="my%20image.png" alt="">`,
+			want: `<img src="file:///Users/you/docs/my%20image.png" alt="">`,
+		},
+		{
+			name: "keeps query and fragment",
+			in:   `<img src="a.png?v=1#top" alt="">`,
+			want: `<img src="file:///Users/you/docs/a.png?v=1#top" alt="">`,
+		},
+		{
+			name: "leaves http URL untouched",
+			in:   `<img src="http://example.com/a.png" alt="">`,
+			want: `<img src="http://example.com/a.png" alt="">`,
+		},
+		{
+			name: "leaves https URL untouched",
+			in:   `<img src="https://example.com/a.png" alt="">`,
+			want: `<img src="https://example.com/a.png" alt="">`,
+		},
+		{
+			name: "leaves data URL untouched",
+			in:   `<img src="data:image/png;base64,AAAA" alt="">`,
+			want: `<img src="data:image/png;base64,AAAA" alt="">`,
+		},
+		{
+			name: "leaves file URL untouched",
+			in:   `<img src="file:///other/a.png" alt="">`,
+			want: `<img src="file:///other/a.png" alt="">`,
+		},
+		{
+			name: "leaves protocol-relative URL untouched",
+			in:   `<img src="//example.com/a.png" alt="">`,
+			want: `<img src="//example.com/a.png" alt="">`,
+		},
+		{
+			name: "leaves empty src untouched",
+			in:   `<img src="" alt="">`,
+			want: `<img src="" alt="">`,
+		},
+		{
+			name: "leaves img without src untouched",
+			in:   `<img alt="">`,
+			want: `<img alt="">`,
+		},
+		{
+			name: "trims surrounding whitespace like browsers do",
+			in:   `<img src=" a.png " alt="">`,
+			want: `<img src="file:///Users/you/docs/a.png" alt="">`,
+		},
+		{
+			name: "leaves whitespace-only src untouched",
+			in:   `<img src="  " alt="">`,
+			want: `<img src="  " alt="">`,
+		},
+		{
+			name: "leaves unparsable src untouched",
+			in:   `<img src="http://[::1" alt="">`,
+			want: `<img src="http://[::1" alt="">`,
+		},
+		{
+			name: "rewrites raw html img with extra attributes",
+			in:   `<img src="a.png" width="300" />`,
+			want: `<img src="file:///Users/you/docs/a.png" width="300" />`,
+		},
+		{
+			name: "rewrites src regardless of attribute order",
+			in:   `<img alt="x" src="a.png">`,
+			want: `<img alt="x" src="file:///Users/you/docs/a.png">`,
+		},
+		{
+			name: "does not touch other elements",
+			in:   `<a href="a.png">link</a><script src="a.js"></script>`,
+			want: `<a href="a.png">link</a><script src="a.js"></script>`,
+		},
+		{
+			name: "does not touch escaped img in code block",
+			in:   `<pre><code>&lt;img src=&quot;a.png&quot;&gt;</code></pre>`,
+			want: `<pre><code>&lt;img src=&quot;a.png&quot;&gt;</code></pre>`,
+		},
+		{
+			name: "preserves surrounding content",
+			in:   "<h1>Title</h1>\n<p>text <img src=\"a.png\" alt=\"\"> more</p>\n",
+			want: "<h1>Title</h1>\n<p>text <img src=\"file:///Users/you/docs/a.png\" alt=\"\"> more</p>\n",
+		},
+		{
+			name: "escapes special characters in attributes",
+			in:   `<img src="a&amp;b.png" alt="&lt;x&gt;">`,
+			want: `<img src="file:///Users/you/docs/a&amp;b.png" alt="&lt;x&gt;">`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := resolveImageSources([]byte(tt.in), baseDir)
+			if string(got) != tt.want {
+				t.Errorf("resolveImageSources() =\n%s\nwant:\n%s", got, tt.want)
+			}
+		})
+	}
+
+	t.Run("encodes special characters in base directory", func(t *testing.T) {
+		got := resolveImageSources([]byte(`<img src="a.png" alt="">`), "/Users/you/my docs")
+		want := `<img src="file:///Users/you/my%20docs/a.png" alt="">`
+		if string(got) != want {
+			t.Errorf("resolveImageSources() = %s, want %s", got, want)
+		}
+	})
+}

internal/renderer/renderer.go

@@ -69,7 +69,9 @@ func NewRenderer(configDir string, themeName string, opts Options) (*Renderer, e
 }
 
 // Render converts Markdown to HTML, applying the theme template if configured.
-func (r *Renderer) Render(markdown []byte) ([]byte, error) {
+// Relative image paths in the content resolve against baseDir,
+// the directory of the source markdown file.
+func (r *Renderer) Render(markdown []byte, baseDir string) ([]byte, error) {
 	context := parser.NewContext()
 
 	// パースは1回だけ
@@ -87,7 +89,8 @@ func (r *Renderer) Render(markdown []byte) ([]byte, error) {
 		return nil, err
 	}
 
-	html := buf.Bytes()
+	// Rewrite before applying the theme so the template's own img tags stay as they are
+	html := resolveImageSources(buf.Bytes(), baseDir)
 
 	if r.tmpl == nil {
 		return html, nil