This site runs a demo / proof of concept of using Drupal content to provide a website user manual. It's a vanilla D9 install with just the user manual configuration added.
As an anon user, basically the only thing you can see on this site is Basic Page content. The user manual content (Help Page nodes) are not accessible through menus, the site search, or direct url access (e.g. /help). For any auth user (see login info on left sidebar), the Help Page nodes are then available to view. Admin users can edit these nodes and add new ones (again, see sidebar for superuser access).
For help or any questions, reach out to Martin H anytime (mattermost or email).
Main features
- Help page content is consolidated into one easy to navigate section, with built in table of contents and prev/next page links
- Since content is normal drupal content, all those tools/options are similarly available: flexible wysiwyg configuration and options, embedded media including screenshots or walkthrough videos, and so on
- Accessible (view only) by user role
- Can be made editable by role as well (e.g. admins), so clients can add their own notes, workflows, and references
- URL aliases to map all pages to the /help path (e.g. /help/page-title, or can configure otherwise)
- Displays using a distinctive theme to help users recognize they are in a conceptually different part of the site (demo shows Olivero but this could be sub-themed for customizations, or any theme could be used)
- The pages, sections, or entire manual can be printed or exported to pdf from simple link in the footer
- Can provide easily visible link in header or sidebar (or drupal toolbar) so help is easy to find anytime
- Can link from other useful places throughout the site as needed (e.g. in help text areas for fields on edit pages)
Install / config
Modules required:
- book (in core)
- pathauto
- content_access (or similar, such as node_view_permissions)
- theme_switcher
- olivero theme (in core) - or your own theme/subtheme
Other modules included in this site just because:
- admin_toolbar
- module_filter
Installation:
- Add/enable modules
- Enable desired help page theme (just enable, don't set as site theme or admin theme)
- Create help_page content type with title and body field, no menu options, revisions on; manage display and place links below body
- Configure pathauto for help_page to set automatic page aliases as /help/page-title
- Use theme_switcher to set theme for help_page pages to Olivero (or desired theme)
- To create a new "book", create new help_page node (this will be the main page / landing page for the manual) with title "Website User Manual"; in node settings for "book outline" select "create a new book"; manually set page alias to "/help"
- Manage blocks for Olivero and add book block to sidebar; configure to display title, set title to "Website User Manual", set to display on book pages only
- For this particular theme, I also disabled the RSS and "made by drupal" blocks in the layout
- Edit user menu and add link to /help (or depending on your site, place a link in some other way so that auth users as they navigate anywhere on the site have a clear and visible way to get to the help pages; e.g. menu link, admin toolbar shortcut, sidebar block; keep in mind the help pages should ideally be findable from both the public theme and the admin theme)
- Review and update user permissions
- In Book, ensure no access to create/admin books; allow admins to manage child pages/hierarchy; allow all auth users to use printer option
- In Node, only allow help_page create/edit/delete to appropriate roles (maybe admin or none at all)
- Then go to the access control page for the help_page content type and set View access to appropriate roles (possibly all auth users) / remove access for anon users
- Done! Now you can add all the content to the help manual / create new nodes as needed.
Future work:
- Automate setup?
- Add tagging and "locked" flag to CT to prevent editing of "core" training pages?
- Possible syncing of "core" manual pages to a central location to allow newer content to distribute to existing sites?
- Sync from an external (json? xml?) file?
- Tag pages by topic so that pages can be selectively excluded (e.g. paragraphs help page if this particular site doesn't use paragraphs)
- Settings page to provide sync location and tags
- Method to generate new sync file?