distributor/docs/integrations/markdown.md

# 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:

```sh
go test ./internal/transform/markdown
```