Markdown Integration

Audience: operators and maintainers who rely on generated HTML outputs from Markdown source files.

Markdown-to-HTML is an implemented file-format integration used by destination transform policy.

Dependency

Rendering uses github.com/yuin/goldmark. The exact version is pinned in go.mod.

Renderer Behavior

The transformer constructs goldmark.New() with no project-specific extensions, parser options, renderer options, templates, CSS, or metadata injection.

Supported output modes:

sidecar: renders each source manifest file ending in .md and writes a generated output beside it with the .md suffix replaced by .html.
index: renders one Markdown source file to index.html at the destination bundle path.

In index mode, transform.markdown_to_html.input may name the source manifest path to render. If input is omitted, the source manifest must list exactly one .md file. The selected input must be a clean 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.

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.

Destination state stores generated outputs with kind: generated, source_path, transform, sha256, size, and optional url.

Boundaries

Markdown rendering does not mutate source bundles, publish files, write .distributor.json, select destination actions, or choose transfer policy. Publish planning decides whether generated HTML is selected for a destination and destination state records the generated output metadata.

Tests

Before changing Markdown renderer behavior, inspect and run:

go test ./internal/transform/markdown

2.3 KiB Raw Blame History