Add configurable D2 SVG output with bundling support

[mnowotnik]

Changes:

• d2/d2.go: add SVG bundling via imgbundler, scale-aware dimensions, and adapter logger
• renderer/fencedcodeblock.go: pass file path and scale through the SVG code path
• markdown/markdown.go: wire the new fenced-code renderer signature
• util/flags.go, util/cli.go, types/types.go: introduce d2-output config and propagate it to MarkConfig
• d2/d2_test.go: cover the SVG path and checksum expectations
• README.md: document the new d2-output option
• go.mod/go.sum: pull in indirect deps needed by SVG bundling

Why:

• Allow uploading original D2 SVGs with bundled assets and respect scaling to avoid manual resizing.

[mnowotnik]

Tested manually on Confluence. Although, d2-scale has much bigger impact on this new svg output, because it takes dimensions to send to Confluence straight from svg rendered by d2 lib instead of from headless chrome. I think this is correct behaviour as far as defaults go, but may be surprising to users.

[mnowotnik]

@mrueg Could you take a look? Pretty straightforward change. And Mark gets SVG with animations and other features.

[mrueg]

Does confluence finally have svg support?

[mnowotnik]

Confluence Cloud for sure. Using this branch of Mark with it right now.

[mnowotnik]

I now see that the SVG support is a debated issue. I attached screen recording with diagram from https://gitlab.com/HariSekhon/Diagrams-as-Code that I uploaded with this Mark branch.

Screen.Recording.2026-02-13.at.11.51.32.mov

[mnowotnik]

Supposedly Confluence Cloud support rendering of SVG attachments. Inline SVG still missing, but we're using attachments anyway.
https://jira.atlassian.com/browse/CONFCLOUD-1762

[mrueg]

thanks for checking!

[mrueg]

What does BundleRemote and BundleLocal do, why do we need to call both?

[mnowotnik]

It's logic from d2cli/main.go:

	svg, bundleErr := imgbundler.BundleLocal(ctx, l, inputPath, svg, cacheImages)
	if bundle {
		var bundleErr2 error
		svg, bundleErr2 = imgbundler.BundleRemote(ctx, l, svg, cacheImages)
		bundleErr = multierr.Combine(bundleErr, bundleErr2)
	}

I think it first bundles local files and if bundle param is set, it additionally tries to bundle remote files.

[mnowotnik]

Put the local bundling outside flag conditional clause to mimic how d2 cli works.

[mrueg]

I think this is something we need to understand better, and need to make sure it does what we want and I'm not sure if I want bundleRemote here.

Copilot summing it up:

BundleLocal takes an SVG document (in) that may reference local image files (e.g., <image href="foo.png">) and rewrites those <image> elements so the href becomes a data URI containing the base64-encoded image bytes:

    It calls the shared bundle(...) implementation with isRemote = false.
    With isRemote=false, only <image href="..."> values that are not http/https URLs are considered eligible (see filterImageElements).
    The worker for each eligible image reads bytes from disk:
        It HTML-unescapes the href first.
        If inputPath != "-" and the href path is relative, it resolves it relative to filepath.Dir(inputPath).
        Then it os.ReadFile(...)s the image.
    It then determines a MIME type (sniffing if needed), base64-encodes the bytes, and replaces:
        from: <image href="some/path.png"
        to: <image href="data:image/png;base64,...."

So the output is still an SVG, but now it’s “self-contained” for local image references.
What BundleRemote does
Go

func BundleRemote(ctx context.Context, l simplelog.Logger, in []byte, cacheImages bool) ([]byte, error) {
	return bundle(ctx, l, "", in, true, cacheImages)
}

BundleRemote does the same kind of bundling, but for remote images referenced by http/https URLs:

    It calls bundle(...) with isRemote = true and an empty inputPath (since it shouldn’t resolve filesystem paths).
    With isRemote=true, filterImageElements selects only <image href="http(s)://..."> references (and skips anything already data:).
    Each worker fetches the image via httpGet(...):
        1 minute per request timeout, and a max body size of maxImageSize (~32 MiB).
        Requires HTTP 200.
        Uses the response Content-Type header if present; otherwise MIME type is sniffed.
    Then it base64-encodes the downloaded bytes and rewrites the <image href="..."> to a data: URI exactly like local bundling.

Shared behavior (both)

Both functions:

    Find <image href="..."> using imageRegex.
    Deduplicate by href so the same image is only fetched/read once (per call).
    Run up to 16 concurrent workers.
    Use a 5 minute overall timeout for the full bundling operation.
    Optionally cache results in the global imgCache (cacheImages=true) keyed by the original href string (so repeated calls can reuse already-encoded outputs).
``

[mnowotnik]

@mrueg Without bundling it doesn't work in Confluence (if remote images are in the given SVG file) , since Confluence SVG engine, at this time, cannot resolve remote images.

Yes, remote bundle can timeout, that's expected.

Actually, bundling should be the default behaviour given Confluence constraints, the only contraindication being not making remote http calls for security reasons.

[Copilot]

Pull request overview

Adds configuration to render D2 fenced code blocks as either PNG (current behavior) or SVG, with optional SVG asset bundling and scale-aware dimensions for Confluence image macros.

Changes:

• Introduce --d2-output (png|svg) and --d2-bundle CLI/TOML/env configuration and propagate through MarkConfig.
• Extend the fenced code block renderer to route D2 rendering through PNG or SVG paths and pass source path/scale.
• Add SVG rendering + bundling implementation in d2 package and expand tests + README docs.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
util/flags.go	Adds d2-output and d2-bundle CLI flags with env/TOML sources.
util/cli.go	Wires new D2 config values into types.MarkConfig.
types/types.go	Extends MarkConfig with D2Output and D2Bundle.
renderer/fencedcodeblock.go	Routes D2 fenced code blocks to PNG vs SVG processing and passes input path/bundle/scale.
markdown/markdown.go	Updates renderer constructor call signature to include the document path.
d2/d2.go	Refactors SVG rendering, adds SVG bundling, and parses SVG dimensions for scale-aware width/height.
d2/d2_test.go	Adds coverage for the SVG path and loosens PNG dimension assertions.
README.md	Documents new --d2-output and --d2-bundle flags.
go.mod	Adds new indirect dependency entries after tidy.
go.sum	Updates sums for new/updated indirect dependencies after tidy.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mnowotnik]

@mrueg Fixed mermaid_test.go cause it's been failing on main also.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mnowotnik]

@mrueg can you give some feedback on this one?

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (3)

mark.go:173

• normalizeAndValidateConfig is called in both Run and ProcessFile, but Run invokes ProcessFile for each matched file, so the validation runs once up-front and then again for every processed file. The operation is idempotent so behavior is correct, but it's wasted work and obscures the invariant of which entry point is responsible for normalization. Consider validating only at the public entry points (and trusting the normalized struct internally), or have Run skip the call when it already validated.

func Run(config Config) error {
	var err error
	config, err = normalizeAndValidateConfig(config)
	if err != nil {
		return err
	}

	api := confluence.NewAPI(config.BaseURL, config.Username, config.Password, config.InsecureSkipTLSVerify)

	files, err := doublestar.FilepathGlob(config.Files)
	if err != nil {
		return err
	}

	if len(files) == 0 {
		msg := "no files matched"
		if config.CI {
			log.Warn().Msg(msg)
		} else {
			return errors.New(msg)
		}
	}

	var hasErrors bool
	for _, file := range files {
		log.Info().Msgf("processing %s", file)

		target, err := ProcessFile(file, api, config)
		if err != nil {
			if config.ContinueOnError {
				log.Error().Err(err).Msgf("processing %s", file)
				hasErrors = true
				continue
			}
			return err
		}

		if target != nil {
			log.Info().Msgf("page successfully updated: %s", api.BaseURL+target.Links.Full)
			if _, err := fmt.Fprintln(config.output(), api.BaseURL+target.Links.Full); err != nil {
				return err
			}
		}
	}

	if hasErrors {
		return fmt.Errorf("one or more files failed to process")
	}

	return nil
}

// ProcessFile processes a single markdown file and publishes it to Confluence.
// Returns nil for the page info when compile-only or dry-run mode is active.
func ProcessFile(file string, api *confluence.API, config Config) (*confluence.PageInfo, error) {
	var err error
	config, err = normalizeAndValidateConfig(config)
	if err != nil {
		return nil, err
	}

d2/d2.go:250

• parseSVGDimensions walks until io.EOF and only returns a result when it finds an <svg> with parseable dimensions. If dec.Token() returns a non-EOF error mid-stream (e.g., malformed XML somewhere later in the document) after a perfectly good outer <svg> was already inspected but had only non-numeric width/height and no viewBox, the function returns that downstream error instead of the dimension parsing context recorded in parseErr. Consider returning parseErr (when non-nil) in preference to unrelated decoder errors so callers get the more actionable failure cause, mirroring the EOF branch.

	for {
		tok, err := dec.Token()
		if err != nil {
			if errors.Is(err, io.EOF) {
				if parseErr != nil {
					return nil, parseErr
				}
				return nil, fmt.Errorf("svg dimensions not found")
			}
			return nil, err
		}

d2/d2.go:162

• When parseSVGDimensions returns an error, ProcessD2SVG logs a warning and continues with boxModel == nil, which sets Width and Height to empty strings. The fenced-code-block template then renders att.Width/att.Height as empty into ac:image attributes. It would be helpful to confirm the Confluence storage-format template tolerates empty width/height (or to set a reasonable fallback) so a parse failure doesn't silently produce broken image markup; at minimum, this fallback behavior is worth a code comment.

	boxModel, err := parseSVGDimensions(out)
	if err != nil {
		log.Warn().
			Err(err).
			Str("title", title).
			Str("input_path", inputPath).
			Msg("could not read svg dimensions; width and height metadata will be omitted")
	}

	checkSum, err := attachment.GetChecksum(bytes.NewReader(d2Diagram))
	if err != nil {
		return attachment.Attachment{}, err
	}

	if title == "" {
		title = checkSum
	}

	width := ""
	height := ""
	if boxModel != nil {
		width = formatSVGDimension(boxModel.width, scale)
		height = formatSVGDimension(boxModel.height, scale)
	}

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

mark.go:172

• Run already calls normalizeAndValidateConfig and then passes the resulting config to ProcessFile, which calls normalizeAndValidateConfig again on the same already-normalized config. This is harmless today but creates an implicit assumption that validation is idempotent. Either skip validation in ProcessFile when called from Run (e.g. via an internal helper that takes an already-validated config), or document that ProcessFile is also a public entry point and the double-validation is intentional.

func ProcessFile(file string, api *confluence.API, config Config) (*confluence.PageInfo, error) {
	var err error
	config, err = normalizeAndValidateConfig(config)
	if err != nil {
		return nil, err
	}

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.