By hand: help pages for your extension
Tutorial 21. Your extension's documentation can live in the same help center as the kernel's, searchable and linked
from the "?" button of your module's pages. This tutorial adds two pages to mysite_hello and connects them. The
mechanisms come from settings/exphelp.ini and the help classes in kernel/classes/help/.
1. Write the pages
extension/mysite_hello/doc/README.md:
---
title: My Site Hello
audience: admin, developer
category: development
order: 10
summary: What the mysite_hello extension adds: greetings, a fetch function, a rating field, a digest.
keywords: mysite_hello, greeting, rating, digest
type: help
---
# My Site Hello
This extension greets visitors on /hello/world/<name>, lets editors compose greetings ...extension/mysite_hello/doc/compose.md, with a heading ## Composing a greeting and the steps for editors.
Front matter keys and their meaning are described in Documenting your extension. Markdown only: the help escapes raw HTML.
2. Commit them
The help serves only files tracked by Git (it reads the repository's index), so commit the pages in the extension's repository:
git -C extension/mysite_hello add doc
git -C extension/mysite_hello commit -m "Added: Help pages for mysite_hello"3. Commit and activate
Commit both pages in the extension's repository. While mysite_hello is active, the help center shows them on its
own ([IndexSettings] ActiveExtensionDocs=enabled, the default), with the ids ext/mysite_hello/README.md and
ext/mysite_hello/compose.md, under Extensions. A README.md and an INSTALL.md on top of
extension/mysite_hello/ would be shown too; every other page belongs in doc/, as Markdown, in English
(Documenting an extension).
Only to show the pages of an extension that is not active, the installation names it in its
settings/override/exphelp.ini.append.php:
[IndexSettings]
ExtensionDocDirs[]=mysite_hello4. Context help
Your extension registers the "?" target of its views in extension/mysite_hello/settings/exphelp.ini.append.php:
[ContextHelp]
Map[hello]=ext/mysite_hello/README.md
Map[hello/compose]=ext/mysite_hello/compose.md#composing-a-greetingThe anchor is the heading as the viewer makes it (lower case, spaces to dashes). An entry whose page is not served is skipped, so the module entry answers instead.
5. Rebuild and check
php bin/php/ezcache.php --clear-tag=ini
./console exp:help index
./console exp:help checkexp:help check reports broken links and images in the help's pages. Then open the help center and search for
"mysite_hello", and press "?" on /hello/compose.
Related pages
- Previous: By hand: translating an extension
- Next: By hand: a PHPUnit test for your extension
- The help system for extensions
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.