Document Markdown rendering integration

2026-05-31 04:07:49 +00:00
parent 93c22884b0
commit 14444c152b
2 changed files with 57 additions and 0 deletions
--- a/docs/integrations/markdown.md
+++ b/docs/integrations/markdown.md
@@ -0,0 +1,55 @@
+# 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.
+
+For each source bundle file ending in `.md`, the transform reads the Markdown source 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.
+
+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.
+
+Only sidecar output mode is supported for current behavior.
+
+## Tests
+
+Before changing Markdown renderer behavior, inspect and run:
+
+```bash
+go test ./internal/transform/markdown
+```
+
+The tests cover sidecar naming, ignored non-Markdown files, raw HTML handling, deterministic output, digest metadata, and size metadata.