The Advanced help module provides a framework that allows module and theme developers integrate help texts in a Drupal site. Although the Advanced help does not provide general help by itself, it provides a powerful and easy framework that modules and themes may use to provide their own help.

Modules and themes utilizing Advanced help should create a subdirectory named help inside their own main directory. Place the file MODULENAME.help.yml (resp. THEMENAME.help.yml) in this subdirectory. formatted similar to the following example:

[about-php]
title = About PHP
file = about-php
weight = -10

[history]
title = History of PHP
parent = about-php

[usage]
title = Usage of PHP
weight = 1

[security] 
title = Security of PHP
weight = 2

[syntax]
title = PHP syntax
parent = usage

This file defines five help topics (inside the square brackets), and some settings for them. See: Advanced help .help.yml file format for a list of defined settings.

All topics are addressed by the module or theme providing the topic, and by the topic id. For Drupal 7, one could use the a format similar to the following example to produce a themed link to popup about a topic:

$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
  'topic' => 'about-php',
));
$output .= ' ' . t('Click the help icon!');

NOTE: In Drupal 9, the function theme() is deprecated. A valid example for Drupal 9 has to be created.

This produces the following output:

<a class="advanced-help-link" title="About PHP"
  onclick="var w=window.open(this.href, 'advanced_help_window',
  'width=500,height=500,scrollbars,resizable');
  w.focus(); return false;"
  href="/help/help_example/about-php?popup=1">
<span>Help</span>
</a>
 Click the help icon!
</div>

This produces a clickable help icon like the one shown below:

Question mark help icon

Inside your help file, you may link to other help topics using this format:

<a href="&topic:module/topic&">topic</a>

This format will ensure the popup status remains consistent when switching between links.

To reference items within the help directory, such as images you wish to embed within the help text, use:

<img src="&path&example.png"/>
<img src="&trans_path&example.png"/>

The trans_path keyword refers to a translated version of the image in the translation directory and may be used it differs from the original.

To reference any normal path in the site, use:

<a href="&base_url&admin/settings/site-configuration">anchor text</a>

NOTE: In previous versions Advanced help did not require the &'s to be wrapped around topic, path, and base_url. This is currently still supported, but will be removed in a future version. By adding the &'s these tokens are now not limited to href="" and src="" parameters.

Search

To enable advanced help search, navigate to Administration → Configuration → Search and metadata → Search settings. Scroll down to Active search modules and tick the box to the left of “Advanced help”. The search form will appear on the top of the advanced help index pages.

If the core Search module is enabled, the contents of the advanced help framework will be indexed on cron. If you enable new modules or themes and wish to immediately index their help text, navigate to Administration → Reports → Status report and click the link “run cron manually”.