The help system for extensions #

Part 8, reference 32. The administration's help center shows the documentation of the kernel and of every active extension. This page collects the settings and file conventions in one place. The explanation is in Documenting your extension, the tutorial in Help pages for your extension, by hand, and the full description in The help system and its specification.

Serving your doc folder #

While the extension is active ([IndexSettings] ActiveExtensionDocs=enabled, the default), the help serves the Git-tracked files of both places, with page ids ext/myext/<path below doc>. Untracked files are not shown. Plain-text pages (.txt, .rst, a README without a suffix) of older extensions still show, as plain text. To show the pages of an extension that is not active, name it in the installation's settings/exphelp.ini.append.php:

[IndexSettings]
ExtensionDocDirs[]=myext

The convention, with a tree and a converted example: Documenting an extension.

Front matter #

---
title: My extension: settings
audience: developer, admin
category: development
order: 10
summary: One sentence, at most 220 characters.
keywords: myext, settings
type: help
---
# My extension: settings

Audience ids (exphelp.ini [AudienceSettings] Audiences[]): editor, admin, developer, user, project-manager, sales-marketing, partner, advocate, designer, hosting, app-creator, website-creator, supporter, sponsor.

Folders #

A folder's README.md is its index page: its title and order are the folder's in the navigation. Link every page from its folder's README, so nothing is orphaned.

Context help #

The header's help button opens help for the current page:

[ContextHelp]
Map[myext]=ext/myext/README.md
Map[myext/settings]=ext/myext/settings.md#clearing-the-cache
Providers[]=myExtHelpContextProvider

Keys are module, module/view, or with a design prefix (admin4l:myext/settings). A provider implements expHelpContextProviderInterface (kernel/classes/help/exphelpcontextproviderinterface.php): helpContext( $module, $view, $design ) returns "path[#anchor]" or null.

Writing rules the help enforces #

• Markdown only: raw HTML is escaped.
• Relative links must point at files that exist; anchors at headings that exist.
• Images in the same folder tree.

Checking #

./console exp:exphelp check

reports broken links, missing anchors and front matter problems, with errors and warnings. Run it before every release of your documentation.

Related pages #

• Previous: admin4 components and tokens
• Next: expservices: remote services for extensions
• The help system
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.