eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Document Markdown rendering integration

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:07:49 +00:00
parent 93c22884b0
commit 14444c152b
2 changed files with 57 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/integrations/markdown.md Normal file
View File

@@ -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.

2
docs/internal/transform.md
View File

@@ -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.