---
title: "Migration"
manual: "Render guides"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3renderguides:migration"
source: "Migration/Index.rst"
rendered: "2026-09-19T06:16:43+00:00"
---

# Migration {#migration}

If you want to migrate from using Sphinx to render TYPO3 documentation
using the render-guides, the file `Documentation/Settings.cfg` has to be
replaced by an XML file, `Documentation/guides.xml`.

To facilitate migration the extension `t3docs/typo3-guides-cli` in this
mono-repository comes with a Symfony console command to automatically migrate
the outdated `Settings.cfg`.

After migration, you can add your `guides.xml` file to your custom repository,
and optionally also remove the old `Settings.cfg` file.

## With official Docker container {#with-official-docker-container}

> [!NOTE]
> Work in progress - Note that we will use `:stable` at a later point to always provide stable
> images with a locked dependency and theme asset set.

To migrate your settings to the new rendering method, run the following
command in your project's root folder:

```shell
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest migrate Documentation
```

The last option is the folder (here: `Documentation`). When running the
command from another folder than the project's root folder, adapt the given
path accordingly.

> [!NOTE]
> Note that the parameter `-v $(pwd):/project` always uses `project` as
> the directory name. You do not need to replace that directory name with
> anything else, because the container rendering depends on this.

## With make {#with-make}

To migrate your settings to the new rendering method, run the following
command in your project's root folder:

```shell
make migrate-settings path=Documentation
```

When running the command from another folder than the project's root folder,
adapt the given path accordingly.

## With ddev {#with-ddev}

To migrate your settings to the new rendering method, run the following
command in your project's root folder:

```shell
ddev composer make migrate-settings path=Documentation
```

When running the command from another folder than the project's root folder,
adapt the given path accordingly.

## With PHP {#with-php}

To migrate your settings to the new rendering method, run the following
command in your project's root folder:

```shell
packages/typo3-guides-cli/bin/typo3-guides migrate Documentation
```

The last option is the folder (here: `Documentation`). When running the
command from another folder than the project's root folder, adapt the given
path accordingly.