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, or source manifest 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.

When transform.markdown_to_html.css_href is set, generated HTML includes a stylesheet link in the document head. The href may be an absolute HTTP(S) URL, a root-relative path, or a relative URL path. Distributor treats this as a link reference only; it does not copy, publish, verify, or manage the CSS file solely because css_href is configured.

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>
optional <link rel="stylesheet" href="..."> when css_href is configured
empty <title>
<body> containing the rendered Markdown body

The wrapper is deterministic. When css_href is omitted, the generated wrapper is unchanged from the unstyled output. When css_href is configured, its escaped link element is part of the generated output bytes.

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.8 KiB Raw Blame History