---
title: "Migration: Markdown to reStructuredText (reST)"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:migrate-markdown-to-rest"
source: "Howto/Migration/MarkdownToReST.rst"
rendered: "2026-09-19T10:25:29+00:00"
---

# Migration: Markdown to reStructuredText (reST) {#migrate-markdown-to-rest}

Markdown is very popular and widely used for documentation. However, ReST is more powerful and flexible.
The TYPO3 documentation toolchain contains a lot of features that are only available with ReST.
Because of the extendability of ReST. This guide explains how to migrate Markdown files to ReST,
using the TYPO3 documentation toolchain.

Unless you have a specific reason to migrate to ReST, it is perfectly fine to keep using Markdown.
The TYPO3 documentation toolchain supports both formats.

> [!NOTE]
> This guide assumes you have already set up the TYPO3 documentation toolchain.
> If you haven't, please follow the instructions in the [Render documentation with the TYPO3 theme](https://docs.typo3.org/permalink/h2document:rendering-docs) guide.

## Converting Markdown to reST {#migrate-markdown-to-rest-conversion}

The first step is to convert the Markdown files to ReST. This can be done using
our rendering toolchain. This will convert the Markdown files to ReST format.
We will use `Documentation-Migrated` as the output directory.

**Linux**

```bash
mkdir -p Documentation-Migrated
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-Migrated
```

**MacOS**

```bash
mkdir -p Documentation-Migrated
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-Migrated
```

**Windows**

```powershell
New-Item -ItemType Directory -Force -Path ".\Documentation-Migrated"
docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --theme=rst --output-format=rst --output Documentation-Migrated
```

> [!NOTE]
> `--output` is resolved inside the container, so the path has to stay
> below the mounted volume (`-v $(pwd):/project`). A path outside it is
> written to the container's own file system and disappears with the
> container, while the command still reports the files as placed. The
> relative `Documentation-Migrated` above satisfies this.

Now we can copy the `guides.xml` from the original directory documentation directory to the new directory. And remove the
option `input-format="md"`. This will tell the rendering toolchain to use the ReST files instead of the Markdown files.

Last step is to swap the directories. Rename the original directory to `Documentation-Markdown` and the new directory `Documentation-Migrated` to `Documentation`.

The basic migration is now done. Some manual adjustments might be necessary, as the conversion is not perfect.

> [!TIP]
> If you notice any issues with the conversion, please report them to the [TYPO3 documentation team](https://docs.typo3.org/permalink/h2document:contact-us).