61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
- `<!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.
|
|
|
|
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.
|