Replace /admin/help page with ILFW specific custom help page

[trubach]

The Problem
The built-in help page that has a link in the admin toolbar and goes to /admin/help gives high level instructions for Drupal site admins, not our content managers.

Describe the solution you'd like
The /admin/help page should be replaced with a custom page that includes:

• A brief description of what the ILFW distribution is at the top
• A link to our documentation at https://drupal.webtheme.illinois.edu/
• A link to the "Getting started" page
• Links to specific features (paragraphs, content types)

To Decide

• The code to override a route HAS to be in a module (illinois_framework_core). Do we put the settings fields in the core module, or keep the settings fields in the theme and pull them into core?

[trubach]

I asked Gemini to outline how to implement replacing the help page using a custom route and controller. Doing it this way would let us potentially extend it later with custom elements, like a accessibility report or broken links. Here's it's response:

---

To replace the default /admin/help page with a custom, extensible dashboard in your Drupal distribution, follow the steps outlined below. This implementation uses a Route Subscriber to override the core route and a Controller to build the new interface.

---

1. Register the Route Subscriber

Register the service in your custom module to intercept core routing.

File: modules/custom/my_distro_core/my_distro_core.services.yml

services:
  my_distro_core.route_subscriber:
    class: Drupal\my_distro_core\Routing\RouteSubscriber
    tags:
      - { name: event_subscriber }

2. Create the Route Subscriber Class

This class identifies the help.main route and modifies it to point to our custom controller.

File: modules/custom/my_distro_core/src/Routing/RouteSubscriber.php

<?php

namespace Drupal\my_distro_core\Routing;

use Drupal\Core\Routing\RouteSubscriberBase;
use Symfony\Component\Routing\RouteCollection;

/**
 * Listens to the dynamic route events to override core help.
 */
class RouteSubscriber extends RouteSubscriberBase {

  /**
   * {@inheritdoc}
   */
  protected function alterRoutes(RouteCollection $collection) {
    // Intercept the main help page route.
    if ($route = $collection->get('help.main')) {
      $route->setDefault('_controller', '\Drupal\my_distro_core\Controller\HelpDashboardController::build');
    }
  }

}

3. Create the Help Dashboard Controller

This controller builds a render array. By using a render array instead of a flat string, we ensure the page remains extensible for future reports (a11y, broken links).

File: modules/custom/my_distro_core/src/Controller/HelpDashboardController.php

<?php

namespace Drupal\my_distro_core\Controller;

use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Custom controller for the /admin/help dashboard.
 */
class HelpDashboardController extends ControllerBase {

  public function build() {
    $build = [];

    // 1. Welcome Header
    $build['header'] = [
      '#type' => 'container',
      '#attributes' => ['class' => ['help-dashboard-header']],
      'title' => [
        '#markup' => '<h1>' . $this->t('Support & Documentation') . '</h1>',
      ],
    ];

    // 2. Extensible Report Section
    // Placeholder for future logic (e.g., A11y or Link Check reports).
    $build['reports'] = [
      '#type' => 'details',
      '#title' => $this->t('Site Health & Reports'),
      '#open' => TRUE,
      'content' => [
        '#markup' => '<p>' . $this->t('Automated reports will appear here.') . '</p>',
      ],
    ];

    // 3. Include Core Help Sections
    // This renders the standard list of module help topics.
    $build['core_help'] = [
      '#type' => 'details',
      '#title' => $this->t('Module Help Topics'),
      '#open' => FALSE,
      'content' => \Drupal::service('help.section_manager')->renderList(),
    ];

    return $build;
  }
}

4. Implementation Details

• Extensibility: To add reports later, you can simply inject more render elements into the $build['reports'] array.
• Permissions: This override respects the existing access administration pages and view help topics permissions defined by the core route.
• Cache: After implementing these files, rebuild the cache to register the subscriber.

drush cr