distributor/docs/roadmap/html_index_mode.md

Roadmap: HTML Index Mode

Purpose

Add a Markdown-to-HTML index mode that renders one selected Markdown artifact to index.html at the destination bundle path.

This feature improves static-site UX and gives link generation and latest path destinations a clean directory-style output to prefer.

Current Implementation Grounding

Current Markdown transformation lives in internal/transform/markdown. It renders every manifest-listed .md file to a sidecar .html file:

report.md -> report.html

Current config validation accepts only markdown_to_html.mode: sidecar. publish.PlanOutputs asks the configured transformer for generated outputs, then destination state records generated outputs with path, kind, source path, transform name, SHA-256, and size. Current destination state has no field for a transform mode beyond the existing transform string.

Goals

• Preserve existing sidecar behavior as the default and supported explicit mode.
• Add markdown_to_html.mode: index.
• In index mode, render exactly one Markdown input to index.html.
• Record index.html as a normal generated output in .distributor.json.
• Keep source manifests unchanged.
• Keep link generation and latest paths straightforward without making them dependencies.

Non-Goals

• Do not add collection index pages.
• Do not add multi-page static-site generation.
• Do not add feeds, notifications, or link generation in this feature.
• Do not require producers to name a file index.md.
• Do not add custom output filenames in v1.

Configuration Shape

Extend existing destination-level transform config:

transform:
  markdown_to_html:
    enabled: true
    mode: index
    input: report.md

Mode semantics:

• sidecar: existing behavior; render each manifest-listed Markdown file to a same-directory .html file.
• index: render one selected Markdown file to index.html at the destination bundle path.

sidecar remains the current/default mode. index is the proposed addition.

Input Selection

Index mode should choose the Markdown input deterministically:

1. If transform.markdown_to_html.input is configured, use that manifest-listed Markdown file.
2. If no input is configured and the source manifest lists exactly one Markdown file, use that file.
3. If no input is configured and there are zero or multiple Markdown files, fail planning with a clear error.

The configured input path must be a safe relative source path, must be listed in the source manifest, and must end in .md.

Input selection happens during planning because it depends on the validated source manifest, not only static config.

Output Semantics

Index mode always writes:

index.html

relative to the destination bundle path.

The generated output should use current state model terms:

• path: index.html;
• kind: generated;
• source_path: selected Markdown file;
• transform: markdown_to_html;
• sha256 and size: digest and byte size of generated HTML.

Replacement, skip, cleanup, and force behavior should treat index.html like any other distributor-managed generated output.

Config validation should reject enabled Markdown-to-HTML transform configuration when publish.html is false. That keeps publish policy and transform intent aligned and avoids silently accepting unused transform config.

Relationship To Other Roadmaps

Link generation should recognize index.html and produce directory-style URLs, but link generation must not be required for index mode.

Latest path destinations work without index mode, but fixed latest destinations produce nicer stable URLs when they publish index.html.

manifest create, pkg/bundle, and remote validation remain source-bundle features and should not depend on transform mode.

Testing Expectations

Suggested coverage:

• config validation accepts mode: sidecar and mode: index;
• current sidecar behavior remains unchanged;
• index mode accepts explicit input;
• index mode chooses the only Markdown file when no input is configured;
• planning fails when index mode has zero or multiple Markdown candidates without explicit input;
• planning fails when explicit input is unsafe, not listed, or not Markdown;
• index mode emits index.html;
• state records index.html as a generated output;
• source-only publication does not write index.html;
• dry-run reports index.html without writing it;
• replacement safely updates prior generated index.html.

Documentation Updates After Implementation

• Update docs/config.md with Markdown-to-HTML modes and input.
• Update docs/integrations/markdown.md with sidecar and index behavior.
• Update docs/operations.md with a static-site example.
• Add or update examples only for implemented behavior.

Keep this roadmap under docs/roadmap/ until implemented.

Decisions

• Enabled Markdown-to-HTML transform config is rejected when publish.html is false.
• Generated output metadata keeps transform: markdown_to_html; the output path and destination config distinguish sidecar from index behavior.
• Future multi-page or collection index generation should be a separate transform, not an expansion of this single-input index mode.

Future Work

• Add a separate collection or site-index transform if distributor later needs multi-page aggregation.
• Consider richer transform metadata only if future state consumers need more than the transform name and output path.
• Consider custom index output names only if fixed index.html proves too limiting for real deployments.