AHS Table of Contents Recipe

Adds in-page navigation (table of contents) to the AHS Recovery site using the tocbot module.

What it provides

Modules

• tocbot — Client-side TOC generation from <h2> headings within <article>.
• block_field — Allows embedding the tocbot block inside a paragraph.

Paragraph types

• TOC — Contains a title field ("On this page") and a block field that renders the tocbot block.

CKEditor 5

• Adds a Skip TOC style to the full_html editor so content authors can apply ignore-toc to <h2> headings directly in the WYSIWYG.

Theme styling

• TOC output is themed to match the Recovery Alberta design: uppercase "ON THIS PAGE" label with a Font Awesome list icon, horizontal links with pipe separators, and top/bottom dividers.

Prerequisites

• The recipe_ahs_layout_pages recipe must be applied first (handled automatically via the recipes key in recipe.yml).
• The ahs_ext_theme custom theme must exist at html/themes/custom/ahs_ext_theme/.
• Composer packages drupal/tocbot and drupal/block_field must be required before applying the recipe.

Installation

1. Require the composer packages

ddev composer require drupal/tocbot drupal/block_field

2. Apply the recipe

ddev drush recipe recipes/recipe_ahs_toc

3. Clear caches

ddev drush cr

Manual steps after installation

Drupal recipes with strict: false use a create-if-not-exists strategy. Config that already exists on the site is skipped, not merged or replaced. Several config files in this recipe modify pre-existing config and will be silently ignored. The following must be verified or configured manually.

1. Add TOC to allowed paragraph types

The recipe creates the TOC paragraph type but does not add it to any content type's layout paragraphs field. For each content type that should support TOC (e.g. layout_page):

• Go to Structure > Content types > [type] > Manage fields
• Edit the layout paragraphs field (field_component)
• Under Reference type > Paragraph types, check TOC
• Save

2. Heading paragraph — form display

The recipe creates field_skip_toc on the heading paragraph type, but the form display already exists and won't be updated. Verify the checkbox appears on the heading edit form:

• Go to Structure > Paragraph types > Heading > Manage form display
• Confirm Skip table of contents is in the form (not hidden)
• Set widget to Single on/off checkbox with Display label enabled
• Recommended weight: 2 (after Title, before Lede)

3. CKEditor — Style toolbar button

The editor.editor.full_html.yml config already exists and won't be updated. To add the Skip TOC style for headings in the WYSIWYG:

• Go to Configuration > Content authoring > Text formats > Full HTML > Configure
• Drag the Style button into the CKEditor toolbar
• Under Style plugin settings, add a style:
  • Label: Skip TOC
  • Element: <h2 class="ignore-toc">
• Save

4. HTML filter — allowed tags

The filter.format.full_html.yml config already exists and won't be updated. If the full_html format uses the Limit allowed HTML tags filter:

• Go to Configuration > Content authoring > Text formats > Full HTML > Configure
• Under Limit allowed HTML tags, add <h2 class="ignore-toc"> to the allowed tags list
• Save

Note: If the filter is disabled (common for full_html), this step can be skipped.

6. Verify tocbot settings

The tocbot.settings.yml is new config and should be created by the recipe. Verify at Configuration > User interface > Tocbot:

• Content selector: article
• Heading selector: h2
• Ignore selector: .ignore-toc
• TOC selector: .js-toc-block
• Min activate: 3

File inventory

recipes/recipe_ahs_toc/
  recipe.yml                          # Recipe definition
  config/
    tocbot.settings.yml               # Tocbot configuration
    paragraphs.paragraphs_type.toc.yml
    field.storage.paragraph.field_block_toc.yml
    field.storage.paragraph.field_skip_toc.yml
    field.field.paragraph.toc.field_block_toc.yml
    field.field.paragraph.toc.field_title.yml
    field.field.paragraph.heading.field_skip_toc.yml
    core.entity_form_display.paragraph.toc.default.yml
    core.entity_view_display.paragraph.toc.default.yml
    core.entity_form_display.paragraph.heading.default.yml
    core.entity_view_display.paragraph.heading.default.yml
    editor.editor.full_html.yml
    filter.format.full_html.yml