---
title: "Adding a manual"
manual: "Backend Manual"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/proudnerds/pn-backend-manual:adding-a-manual@1.0"
source: "AddingAManual.rst"
rendered: "2026-10-17T07:19:17+00:00"
---

# Adding a manual {#adding-a-manual}

A manual is a Markdown file in a sitepackage or custom extension, registered as
a dashboard widget in the `Services.yaml` of that same extension.

## Write the Markdown file {#adding-a-manual-file}

Put the file in `Resources/Private/` of your sitepackage or custom
extension, for example `Resources/Private/Manual/EditorManual.md`.

> [!WARNING]
> Not in `Resources/Public`: every file there can be downloaded without
> logging in.

**Resources/Private/Manual/EditorManual.md**

```markdown
---
type: manual
version: "1.0"
---

# Editor manual example.org

One or two sentences about who this manual is for. Everything before the
first h2 is the introduction shown in the widget.

## Working in TYPO3

### Where to find what

| You want to | Where |
|---|---|
| Manage pages | **Content › Layout** |

![The page tree in Content › Layout](../../Public/Manual/page-tree.png)

## News items

Read the [TYPO3 Editors Tutorial](https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/).
```

The file is GitHub Flavored Markdown. A complete example is
[Documentation/Example/EditorManual.md](https://github.com/proudnerds-typo3/pn_backend_manual/blob/main/Documentation/Example/EditorManual.md)
in the repository.

## How the file is read {#adding-a-manual-reading}

| Markdown | Result |
| --- | --- |
| Front matter (`---` … `---`) | Ignored. Use it for other tools, such as a Word export. It must be valid YAML. |
| First `#` heading | Title of the manual, shown as h1 in the full view. Not repeated in the body. Without it, the widget title is used. |
| Text before the first `##` | Introduction, shown in the widget and at the top of the full view. |
| `##` headings | Chapters: the table of contents in the widget and in the full view. |
| `###` headings | Sections of the chapter above them; also in the table of contents of the full view with [contentsDepth: 2](https://docs.typo3.org/permalink/proudnerds/pn-backend-manual:confval-option-contentsdepth@1.0). |
| `##` and `###` headings | Get an anchor `#manual-<slug>`, for example `## News items` becomes `#manual-news-items`. Use these for links within the manual. With [numbered](https://docs.typo3.org/permalink/proudnerds/pn-backend-manual:confval-option-numbered@1.0) the number is shown but not part of the anchor. |
| Tables | Backend table style. |
| Links to other sites | Open in a new window, with a hidden "opens in a new window" for screen readers. |
| Raw HTML, `javascript:` links | Stripped, also from the title, the table of contents and alt texts. |
| Images | See [Images and screenshots](https://docs.typo3.org/permalink/proudnerds/pn-backend-manual:adding-a-manual-images@1.0). |

## Images and screenshots {#adding-a-manual-images}

Write image paths **relative to the Markdown file**, so the manual also
previews correctly in your IDE or on GitHub and Bitbucket:

```text
Resources/
├── Private/Manual/EditorManual.md        ![…](../../Public/Manual/page-tree.png)
└── Public/Manual/page-tree.png
```

Only files inside `Resources/Public` of the **same extension** are shown,
with a cache-busting URL, so a replaced screenshot shows up straight away.

An image that is missing or lies elsewhere is replaced by its alt text in
italics, as a browser does with a broken image. That applies to another folder,
a symlink out of `Resources/Public`, an absolute path, a URL, a data URI,
and file names with `#` or `?`. So always write a meaningful alt text: it
is what screen readers read, and what editors see while a screenshot does not
exist yet.

Next: [register the manual as a widget](https://docs.typo3.org/permalink/proudnerds/pn-backend-manual:configuration@1.0).