ADR 9: Markdown

Context

XML is not appropriate for writing and reading by humans. Its verbose and uniform syntax hampers reading and navigating the source code. On the other side, XML provides excellent means for defining arbitrary structure. IT4KT uses it to structure scenarios into sections and steps. Inside of them usual HTML elements can be mixed with special blocks like tasks, comments and notes for a lecturer.

Decision

We decided to use extended version of the Markdown. Markdown is probably the most popular of the lightweight markup languages. It has simple and intuitive syntax compared to alternatives, like reStructuredText.

We decided to use Markdown headers with special keywords for outher structure and Markdown blockquotes for inner blocks:

## Goals
- The word "Goals" is a keyword, it defines the goals section.
- {goal-id} Some sections may limit their contents and do some custom processing

## Step

Content of the step

## Step: Title {goal-id}

Step with the title and reference to the goal.

> Task:
> Block type keyword must be written on the first line and followed by the colon.

One of the main goals of chosen syntax was to use existing elements of Markdown, so it would not require special support in text editors.

Headers are a natural way to divide text into sections. In the format of scenarios where sections are fixed, headers with keywords define boundaries of each section.

Inner blocks can be placed inside of textual content and can contain arbitrary textual content (e.g. several paragraphs), so we needed to use some syntax that allows to define both the start and the end of the block. The syntax should also support nesting of usual Markdown text, so syntax highlighting in the editors would work correctly. For these reasons blockquotes were chosen.

The keywords support localization, so they can be written in the same language as the rest of the page.

Status

Accepted.

Consequences

Scenarios and pages can be written in an easy to write and read format.

Because now there are two input formats, the only common format for further processing of page content is the HTML.