Add Markdown HTML publication

docs/cli.md

@@ -20,7 +20,7 @@ distributor inspect
 
 `version` prints the application name and version. The default development version is `dev`; release builds may replace it at build time.
 
-`run --config <path>` executes configured local-to-local pipelines that publish source files only.
+`run --config <path>` executes configured local-to-local pipelines that publish source files, generated HTML files, or both.
 
 `run --config <path> --dry-run` discovers source bundles, inspects destination state, and prints planned actions without writing files.
 
@@ -28,7 +28,7 @@ distributor inspect
 
 `inspect <path>` validates discovered local source bundles and prints a concise normalized summary.
 
-Remote backends and HTML publication are not implemented yet.
+Remote backends are not implemented yet.
 
 ## Flag reference
 
@@ -70,3 +70,9 @@ Publish the local example:
 ```sh
 go run ./cmd/distributor run --config examples/local-publish.yml
 ```
+
+Publish the local HTML example:
+
+```sh
+go run ./cmd/distributor run --config examples/local-html.yml
+```

docs/config.md

@@ -10,7 +10,7 @@ If `--config` is omitted during run, the built-in default path is:
 /usr/local/etc/distributor/config.yml
 ```
 
-The current implementation supports local-to-local source-file publication. Remote backends and HTML publication are not implemented yet.
+The current implementation supports local-to-local publication of source files, generated HTML files, or both. Remote backends are not implemented yet.
 
 ## Minimal config
 
@@ -74,7 +74,7 @@ Backends:
 Destination policy:
 
 - `publish.source`: publish source artifacts.
-- `publish.html`: publish generated HTML artifacts.
+- `publish.html`: publish generated HTML artifacts from Markdown source files.
 - `transfer.on_destination_same`: `skip` or `fail`, defaults to `skip`.
 - `transfer.on_destination_older`: `replace` or `fail`, defaults to `replace`.
 - `transfer.on_destination_newer`: `skip` or `fail`, defaults to `skip`.
@@ -82,6 +82,8 @@ Destination policy:
 
 When `publish.html` is true, `transform.markdown_to_html.enabled: true` and `transform.markdown_to_html.mode: sidecar` are required.
 
+Markdown-to-HTML sidecar generation writes `report.html` for `report.md` and does not mutate the source bundle.
+
 ## Secrets
 
 Do not put literal secrets in config files. S3 credentials may refer to environment variable names with:

docs/internal/publish.md

@@ -8,7 +8,7 @@
 
 Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transfer policy, destination bundle path, and existing destination state.
 
-Output is a plan with an action, reason, and selected source outputs. Execution writes selected source files and `.distributor.json` for publish or replacement actions.
+Output is a plan with an action, reason, and selected source or generated outputs. Execution writes selected source files, generated files, and `.distributor.json` for publish or replacement actions.
 
 ## Actions
 
@@ -16,7 +16,7 @@ Supported actions are publish new, replace older destination, skip same source,
 
 ## Boundaries
 
-The current implementation publishes source files only. HTML generation and remote backend execution are not implemented.
+The current implementation publishes source files and Markdown-to-HTML sidecar outputs. Remote backend execution is not implemented.
 
 The package uses `internal/state` for destination comparison and `internal/storage` for IO. It does not parse CLI flags or load config files.
 

docs/internal/transform.md

@@ -0,0 +1,23 @@
+# Transform
+
+## Purpose
+
+`internal/transform` defines generated publication artifacts. `internal/transform/markdown` implements Markdown-to-HTML sidecar generation.
+
+## Inputs and outputs
+
+Inputs are a validated source bundle and source backend. Outputs include destination path, source path, transform id, generated bytes, SHA-256, and size.
+
+## Markdown behavior
+
+Markdown files ending in `.md` generate `.html` files in the same logical directory. Non-Markdown files do not generate outputs. Raw HTML embedded in Markdown is not passed through by the renderer.
+
+Generated HTML is deterministic for the same source content and transform configuration.
+
+## Boundaries
+
+Transforms do not publish files, mutate source bundles, or write destination state. Publish planning selects and writes transform outputs.
+
+## Tests
+
+Before changing transform behavior, inspect tests under `internal/transform`.

docs/operations.md

@@ -14,6 +14,12 @@ Run the local publication:
 go run ./cmd/distributor run --config examples/local-publish.yml
 ```
 
+Run the local HTML publication:
+
+```sh
+go run ./cmd/distributor run --config examples/local-html.yml
+```
+
 ## Filesystem layout
 
 Source bundles are discovered beneath the configured local source root. Destination bundle paths preserve the source bundle path relative to that source root.
@@ -22,7 +28,7 @@ The maintained example writes under `workspace/`, which is ignored by Git.
 
 ## Destination state
 
-Each published destination bundle contains `.distributor.json`. This state file records the source manifest and copied source outputs. It is the authoritative marker that a destination path is managed by `distributor`.
+Each published destination bundle contains `.distributor.json`. This state file records the source manifest, copied source outputs, and generated outputs. It is the authoritative marker that a destination path is managed by `distributor`.
 
 `manifest.json` from the source bundle is not copied as destination state.
 
@@ -36,4 +42,4 @@ If a write fails during local publication, `distributor` removes outputs written
 
 ## Caveats
 
-Only local-to-local source-file publication is implemented. SSH, S3, HTML generation, notification, and force overwrite behavior are not implemented.
+Only local-to-local publication is implemented. SSH, S3, notification, and force overwrite behavior are not implemented.