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

Add integration contract documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-04 12:15:21 +00:00
parent ecc5254e6b
commit a81f686fae
10 changed files with 473 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/integrations/markdown.md
View File

@@ -1,27 +1,27 @@
# Markdown Integration
## Purpose
Audience: operators and maintainers who rely on generated HTML outputs from Markdown source files.
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.
Markdown-to-HTML is an implemented file-format integration used by destination transform policy.
## 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.
Rendering uses `github.com/yuin/goldmark`. The exact version is pinned in `go.mod`.
## Renderer behavior
## Renderer Behavior
`internal/transform/markdown.New` constructs the renderer with `goldmark.New()` and no project-specific extensions or renderer options.
The transformer constructs `goldmark.New()` with no project-specific extensions, parser options, renderer options, templates, CSS, or metadata injection.
The transform supports two output modes:
Supported 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.
- `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` 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`.
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.
## Wrapper
## HTML Wrapper
Rendered Markdown body HTML is wrapped in a fixed document shell:
@@ -33,7 +33,7 @@ Rendered Markdown body HTML is wrapped in a fixed document shell:
The wrapper is deterministic and does not read configuration, templates, CSS, or source manifest metadata.
## Output metadata
## Output Metadata
Generated outputs record:
@@ -43,18 +43,16 @@ Generated outputs record:
- 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 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.
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:
```bash
```sh
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.