# PR#88: Markdown Reports in the Artifact Index

> This document describes the change of this pull request at the time it was made.
> Later pull requests may change the behaviour without updating it.

## The Problem

The artifact index lists a report directory by its index page alone.
werkcrappit writes `mutation-crap.md` into PIT's report directory, next to PIT's `index.html`.
In hsadmin-ng's builds the file was archived but never listed; it could only be fetched by its path.
And opened by its path, a `.md` file came as `application/octet-stream` and the browser downloaded it, since Spring knows no type for Markdown.

## Non-Goals

- Rendering Markdown as HTML.
- Listing other file types next to an index page, such as werkcrappit's `mutation-crap.json`: it is for machines.
- Listing files deeper inside a report; they belong to the report they lie in.

## The Scenarios

#### Scenario#88.01: a Markdown report beside an index page is listed

- **Given** a build whose `reports/pitest/` holds PIT's `index.html` and werkcrappit's `mutation-crap.md`
- **When** the artifact page of that build is shown
- **Then** it links `reports/pitest/index.html` and `reports/pitest/mutation-crap.md`
- **And** neither the JSON next to them nor a Markdown file deeper in the report

##### Verified by

- [UiControllerTest "artifact index lists a Markdown report next to another tool's index page"](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)

#### Scenario#88.02: a Markdown report is shown, not downloaded

- **When** a `.md` artifact is requested
- **Then** it is served as `text/plain;charset=UTF-8` with `Content-Disposition: inline`

##### Verified by

- [ArtifactFileControllerTest "a Markdown report is shown as UTF-8 text"](../../src/test/kotlin/de/hoennig/werkator/server/ArtifactFileControllerTest.kt)

## The Solution

`UiController.markdownReports` adds the `.md` files lying directly in a listed report directory, in `reports/` itself, or in one of its direct sub-directories.
It is the same depth the index-less report pages are searched at, so a report tree cannot flood the index.
`ArtifactFileController` serves `md` like `log`, as UTF-8 plain text; plain text, not `text/markdown`, because every browser shows plain text inline.