From 14444c152bd8a5ff3c6f5178327d25f3aedeb40d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 31 May 2026 04:07:49 +0000 Subject: [PATCH] Document Markdown rendering integration --- docs/integrations/markdown.md | 55 +++++++++++++++++++++++++++++++++++ docs/internal/transform.md | 2 ++ 2 files changed, 57 insertions(+) create mode 100644 docs/integrations/markdown.md diff --git a/docs/integrations/markdown.md b/docs/integrations/markdown.md new file mode 100644 index 0000000..a15d883 --- /dev/null +++ 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: + +- `` +- `` +- 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. + +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. diff --git a/docs/internal/transform.md b/docs/internal/transform.md index 88b7d69..0de180b 100644 --- a/docs/internal/transform.md +++ b/docs/internal/transform.md @@ -18,6 +18,8 @@ Markdown files ending in `.md` generate `.html` files in the same logical direct Generated HTML is deterministic for the same source content and transform configuration. +See `docs/integrations/markdown.md` for the Goldmark integration contract. + ## Failure behavior Transform resolution fails when a requested transform id is not registered. Markdown rendering fails when the source file cannot be read or rendered. Publish planning fails when HTML output is requested and the selected transform produces no outputs for a bundle.