` - `<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: ```bash 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.

# 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: - `` - `` - UTF-8 `` - empty `` - `<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: ```bash 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.