Markdown Integration

Purpose

Markdown-to-HTML is the only implemented external file-format integration. This note documents the renderer behavior that is externally visible in generated destination artifacts.

Dependency

Rendering uses github.com/yuin/goldmark. The exact dependency version is pinned in go.mod; review that file before changing renderer behavior or diagnosing version-specific output changes.

Renderer behavior

internal/transform/markdown.New constructs the renderer with goldmark.New() and no project-specific extensions or renderer options.

For each source bundle file ending in .md, the transform reads the Markdown source and generates an HTML sidecar in the same logical directory. The output path replaces the .md suffix with .html, so report.md produces report.html. Non-Markdown source files produce no Markdown outputs.

Raw HTML embedded in Markdown is not passed through by the current renderer behavior. Tests allow Goldmark's disabled-or-escaped raw HTML output forms and reject literal script tags in generated HTML.

Wrapper

Rendered Markdown body HTML is wrapped in a fixed document shell:

<!doctype html>
<html lang="en">
UTF-8 <meta charset>
empty <title>
<body> containing the rendered Markdown body

The wrapper is deterministic and does not read configuration, templates, CSS, or source manifest metadata.

Output metadata

Generated outputs record:

destination path;
source path;
transform id markdown_to_html;
SHA-256 digest of the wrapped HTML bytes;
byte size of the wrapped HTML bytes.

Boundaries

Markdown rendering does not mutate source bundles, publish files, write .distributor.json, select outputs, or choose transfer actions. Publish planning decides whether generated HTML is selected for a destination.

Only sidecar output mode is supported for current behavior.

Tests

Before changing Markdown renderer behavior, inspect and run:

go test ./internal/transform/markdown

The tests cover sidecar naming, ignored non-Markdown files, raw HTML handling, deterministic output, digest metadata, and size metadata.

2.1 KiB Raw Blame History