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:

```text
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:

```yaml
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:

```text
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.