Quick start

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/.

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.

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 and is required even when it has 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.

Install the renderer#

The package is installed 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:dev-main

Render and finish the site#

The render writes the documents. The finishing step copies the drop-in, draws the custom elements into the HTML, writes the search index and checks the references introduced after the render:

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 should carry the Soul type, canvas, header, mode switch and footer. It remains readable with JavaScript disabled; JavaScript adds the interactive behaviour rather than the content.

Where to continue#

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