Migration: Markdown to reStructuredText (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 guide.

Converting Markdown to reST

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.

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

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

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.