Adding a manual
A manual is a Markdown file in a sitepackage or custom extension, registered as
a dashboard widget in the Services. of that same extension.
Write the Markdown file
Put the file in Resources/ of your sitepackage or custom
extension, for example Resources/.
Warning
Not in Resources/: TYPO3 publishes that folder under
public/_, so every file in it can be downloaded without
logging in.
---
version: "1.0"
date: 2026-10-16
---
# 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** |
## 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 in the repository.
How the file is read
| Markdown | Result |
|---|---|
Front matter (--- … ---) | version and date (YYYY-) are shown under the title
of the full view, so readers see how recent the manual is. Other
keys are ignored; use them 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. |
## and ### headings | Get an anchor #manual-<slug>, for example ## News items
becomes #manual-. Use these for links within the
manual. With numbered the number is
shown but not part of the anchor. |
| Tables | The table style of the backend lists (table-,
table table-); long text wraps inside the cells. |
| 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.
To show HTML as an example, write it as code between backticks:
`<strong>` (one backtick on each side). |
| Code between backticks | The code color of the backend, on a light surface; long code such as a URL wraps. |
| Images | See Images and screenshots. |
Images and screenshots
The manual and its images live in different folders: the manual in
Resources/, which is not published, and the images in
Resources/, which is published so the browser can load them.
Resources/
├── Private/
│ └── Manual/
│ └── EditorManual.md ← the manual
└── Public/
└── Manual/
└── page-tree.png ← the imageIn the manual, write the path to the image relative to the Markdown file:
The path starts in the folder of the manual, Resources/:
../goes up one folder, toResources/Private/ - the second
../goes up toResources/ Public/goes down to the imageManual/ page- tree. png
This is the usual way to link an image in Markdown, so the image also shows in the preview of your IDE and on GitHub or Bitbucket.
Only files inside Resources/ of the same extension are shown,
with a cache-busting URL, so a replaced screenshot shows up straight away.
Tip
Avoid spaces in file names, for example page- instead of
page tree.. The image is shown either way, but the core cannot
add the cache-busting part to a URL of a file with a space in its name.
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/, 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.