---
title: "Automatic re-rendering when writing documentation locally"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:live-rendering"
source: "Howto/RenderingDocs/Watch.rst"
rendered: "2026-09-19T10:25:29+00:00"
---

# Automatic re-rendering when writing documentation locally {#live-rendering}

In case you write complex `reST` markup you may want immediate visual
feedback on your changes, without triggering the rendering manually every time.

`render-guides` can serve the rendered documentation via a local web-server
and automatically re-render the documentation when changes in the source files
are detected.

This enables a WYSIWYG-like editing experience with your editor
and browser side-by-side.

-   [Prerequisites](https://docs.typo3.org/permalink/h2document:prerequisites)
-   [Usage with Docker](https://docs.typo3.org/permalink/h2document:usage-with-docker)
-   [Usage with Docker Compose](https://docs.typo3.org/permalink/h2document:usage-with-docker-compose)
-   [Usage with DDEV](https://docs.typo3.org/permalink/h2document:usage-with-ddev)
-   [Limitations](https://docs.typo3.org/permalink/h2document:limitations)

## Prerequisites {#rendering-wysiwyg-prerequisites}

Configure the rendering as described here: [Rendering the Documentation folder locally with Docker](https://docs.typo3.org/permalink/h2document:render-documentation-with-docker).

The only thing that changes is the render command you use (see below).

## Usage with Docker {#rendering-wysiwyg-docker}

**Linux**

```bash
docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
xdg-open "http://localhost:1337/Index.html"
```

**MacOS**

```bash
docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
open "http://localhost:1337/Index.html"
```

**Windows**

```powershell
docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --config="Documentation" --watch
start "http://localhost:1337/Index.html"
```

The command above can also be added to your project's `Makefile`.

Or you can create a bash alias like:

```bash
alias render-wysiwyg="docker run --rm -it --pull always \
                        -v './Documentation:/project/Documentation' \
                        -v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \
                        -p 1337:1337 ghcr.io/typo3-documentation/render-guides:latest --watch"
```

> [!NOTE]
> If your host operating system already utilizes the TCP port `1337`
> you need to adapt that command to use another free TCP port. For this
> you can change the port number behind the `-p` parameter. To use
> port `8080` the bash code needs to be adapted like this: `-p 8080:1337`.
>
> Also adapt the port in the URL. In the example above the server would be
> accessible via `http://localhost:8080` instead of `http://localhost:1337`.

## Usage with Docker Compose {#rendering-wysiwyg-docker-compose}

If you are using [docker-compose](https://docs.docker.com/compose/) to manage your
development environment, you can add a service for the automatic re-rendering like this:

**docker-compose.yml**

```yaml
services:
  render-wysiwyg:
    restart: "no"
    image: ghcr.io/typo3-documentation/render-guides:latest
    ports:
      - "1337:1337"
    volumes:
      - ./Documentation:/project/Documentation
      - ./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp
    command: ["--config=Documentation", "--watch"]
```

> [!NOTE]
> `render-guides` was never optimized for long running services. You might need
> to restart the container from time to time to free up resources.

## Usage with DDEV {#rendering-wysiwyg-ddev}

For integration with DDEV projects, a DDEV addon is available at
[https://github.com/TYPO3-Documentation/ddev-typo3-docs](https://github.com/TYPO3-Documentation/ddev-typo3-docs).

When you start your DDEV project, this addon starts the automatic re-rendering
of the documentation at `http://<yourproject>.ddev.site:1337/`.

In this environment, users do not need to execute a manual `docker run` command.

## Limitations {#rendering-wysiwyg-limitations}

Not all changes in the source files can be detected automatically,
or will impact the rendered output immediately:

-   Changes in `guides.xml`
-   New added files
-   Menu changes
-   Moving files

**In such cases, a manual re-rendering is required.**

> [!NOTE]
> Some editors (like `VIM`) create temporary files when opening files
> for editing. This will not be detected as a change to the
> actual file and thus not trigger a re-rendering.