---
title: "Quick start"
description: "Render a local documentation site from an empty project directory."
canonical: quickstart.html
navigation-title: "Quick start"
---

<a id="quick-start"></a>

# Quick start

- [What the machine needs](#what-the-machine-needs)
- [Write the project files](#write-the-project-files)
- [Install the renderer](#install-the-renderer)
- [Render and finish the site](#render-and-finish-the-site)
- [Where to continue](#where-to-continue)

Render a local documentation site from an empty project directory. Run every
command below from that directory. The renderer lives under `.renderer/`
and the documents under `docs/`.

<a id="what-the-machine-needs"></a>

## What the machine needs

PHP 8.2 or newer, Composer and Node. The theme brings phpDocumentor Guides,
the syntax highlighter, the Markdown parser, the frontend drop-in and the
finishing step with it.

<a id="write-the-project-files"></a>

## Write the project files

Create `docs/guides.xml`:

docs/guides.xml

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<guides xmlns="https://www.phpdoc.org/guides"
        input-format="rst"
        links_are_relative="true"
        theme="soul"
        default_code_language="text">
    <project title="Example Project" version="1.0"/>
    <extension class="TYPO3\Soul\GuidesTheme\DependencyInjection\SoulExtension"/>
</guides>
```

The `<extension>` element registers the theme. It is mandatory, even with
no configuration of its own.

Create the entry page:

docs/index.rst

```text
:navigation-title: Home

===============
Example Project
===============

This page was rendered with the Soul Guides theme.

.. note::

   The renderer, theme, search and frontend now travel together.
```

<a id="install-the-renderer"></a>

## Install the renderer

The package lives outside the documentation tree:

```bash
mkdir -p .renderer
composer --working-dir=.renderer init --no-interaction --name=example/documentation
composer --working-dir=.renderer require \
  --no-interaction --no-progress \
  typo3/soul-guides-theme
```

<a id="render-and-finish-the-site"></a>

## Render and finish the site

The render writes the documents. The finishing step copies the drop-in and
draws the custom elements into the HTML. It writes the search index and
checks the references the render did not know:

```bash
.renderer/vendor/bin/guides docs --output=site -c docs --fail-on-error
node .renderer/vendor/typo3/soul-guides-theme/resources/dist/soul-finish.js site
php -S localhost:8000 -t site
```

Open `http://localhost:8000`. The page carries the Soul type, canvas,
header, mode switch and footer. It stays readable with JavaScript off.
JavaScript adds the behaviour, not the content.

<a id="where-to-continue"></a>

## Where to continue

| Need | Read |
| --- | --- |
| a complete project and GitHub Pages workflow to copy | [A project to copy](example.md) |
| every setting in `guides.xml` | [Configuration](configuration.md) |
| cards, grids, tabs, accordions and landing-page bands | [Directives](directives.md) |
| the build, the finishing step and the publication boundary | [Publishing it, in CI](publishing.md) |
| the renderer's own reStructuredText and Markdown output | [Core markup, and what it becomes](markup.md) |