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.

The transform supports two output modes:

sidecar: reads each source bundle file ending in .md 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.
index: renders one selected Markdown source to index.html at the destination bundle path.

In index mode, transform.markdown_to_html.input can name the source manifest path to render. If input is omitted, the manifest must list exactly one Markdown file. The selected input must be a safe relative source path, must be listed in the source manifest, and must end in .md.

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.

Publish planning chooses the configured mode and input for each destination. Markdown rendering does not inspect destinations, publish files, write .distributor.json, or choose transfer actions.

Tests

Before changing Markdown renderer behavior, inspect and run:

go test ./internal/transform/markdown

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

2.7 KiB Raw Blame History