roberskine / craft-user-manual

📚 Help Section Plugin for Craft CMS.

Craft User Manual plugin for Craft CMS 4.x and Craft CMS 5.x

Craft User Manual allows developers (or even content editors) to provide CMS documentation using Craft's built-in sections (singles, channels, or structures) to create a "User Manual" or "Help" section directly in the control panel.

Requirements

This plugin requires Craft CMS 4.0.0 or later.

Installation

Craft 4 and Craft 5

To install the plugin in your Craft 4 project, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require hillholliday/craft-user-manual
   

Wondering why it says hillholliday and not roberskine as the org? This package was originally submitted as hillholliday, and to preserve the artifacts on Packagist we have kept it as hillholliday.

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for usermanual.

4. Select the section the plugin should use as the User Manual page in the CP.

   • (Optional) - Replace the plugin's name to something your user's will understand.
   • (Optional) - Use more than the default body fieldhandle by setting up custom template overrides.

5. Click the User Manual link in the CP nav.

Craft 3

To install the plugin in your Craft 3 project, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require hillholliday/craft-user-manual:2.1.2
   

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for usermanual.

4. Select the section the plugin should use as the User Manual page in the CP.

   • (Optional) - Replace the plugin's name to something your user's will understand.
   • (Optional) - Use more than the default body fieldhandle by setting up custom template overrides.

5. Click the User Manual link in the CP nav.

Configuration

• All settings may be optionally configured using a config file. The values, contained in config.php, are described below:

pluginNameOverride

Intuitive, human-readable plugin name for the end user.

templateOverride

For more control over the output, you may optionally override the default template.

Path is relative to ../craft/templates/.

section

Entries in this section must have associated urls.

enabledSideBar

Enables the sidebar on the manual page

Defaults to true.

Some notes

• The plugin currently only pulls in the body field from each entry in the selected section, unless you're using a template override.
• While the User Manual section works best with Structures, you can certainly get away with using a one-off Single.
• If you're running Craft Client or Craft Pro make sure your content editors don't have permission to edit whatever section you've selected to use as your User Manual
• Only sections with entry URLs may be used as your User Manual section.

Thanks

This plugin was inspired by the team over at 70kft for their work on Craft-Help. While their plugin is definitely more flexible in terms of writing custom markdown in separate files, we wanted to create something that would make it easier for anyone to edit documentation without making any changes to the server. This works particularly well for larger projects where more than one person (especially non-devs) are writing documentation for how to use the CMS.

Releases

• 5.0.0 - Craft 5 support! Thanks to John Morton and Dalton Rooney for your contributions.
• 4.0.0 - Craft 4 support! Thanks to Chris DuCharme for migrating up to Craft 4.
• 2.1.0 - Merging PRs from JorgeAnzola and sameerast
• 2.0.3 - Forcing updating to plugin store
• 2.0.2 - Merging in @aaronbushnell's fix for incorrect reference to asset bundle.
• 2.0.1 - Merging in @mgburns' fix for Craft 3 deprecation warnings.
• 2.0.0 - Merging in @jcdarwin Craft 3 port. Craft 3 version of Craft User Manual.
• 1.1.1 - Adding in RTL language support.
• 1.1.0 - Merging in @timkelty's work which includes template overrides, updated error prompts, and other misc improvements.
• 1.0.1 - Adding support for plugin custom icons in Craft 2.5.
• 1.0.0 - Initital release of Craft User Manual.

We hope this plugin is useful, and we'd love to hear any suggestions or issues you may have. @erskinerob.

Brought to you by Rob Erskine.

craft-user-manual's Issues

Craft 5 Version?

Do you have plans to release a craft 5 compatible version?

Failed to instantiate component or class UserManualAsset

Craft 3 install, using the project.yaml setup. On local my UserManual works great, but on both development and production servers, I get the following error when trying to visit the UserManual to view the pages - editing them works as expected.

Failed to instantiate component or class "hillholliday\usermanual\assetbundles\usermanual\UserManualAsset".

Clearing cache doesn't trigger anything. Any ideas on a fix?

Craft 4 Update Versioning Issue in the Read Me

Appreciate all of your work! Pretty minor lil issue, but saw in a recent change that you updated it to hillholliday/craft-user-manual: 2.1.2 but I believe it should actually be hillholliday/craft-user-manual: 4.0.0 so the composer.json file shows "hillholliday/craft-user-manual": "^4.0.0",

Update readme on how to setup Section

Hello,

I'm having trouble with setting up the section propery. What URL does it expect? First entry is displayed correctly, but in the navigation, any other link throws a 404 page no matter what level I move it to.

Port to Craft 4

Creating a ticket to prepare this plugin for Craft 4.

Going to try to work on this the week of 2022-05-02.

Craft 4 Install fail

I saw that user manual is now ready for Craft 4 so I attempted to install it however after running the composer command from the readme and also tried from the Craft plugin store

composer require roberskine/craft-user-manual

composer require roberskine/craft-user-manual && php craft plugin/install usermanual

It fails with this error message in red:

  [InvalidArgumentException]                                                 
  Could not find a matching version of package roberskine/craft-user-manua   
  l. Check the package spelling, your version constraint and that the pack   
  age is available in a stability which matches your minimum-stability (be   
  ta).  

User Manual Entries not accessible if administrative changes disabled

Hi

We currently use the 'allowAdminChanges' => false, option in general.php in our Staging and Production environments. However when we try to access the User manual entries (admin/usermanual), it seems to redirect to admin/settings/plugins/usermanual instead and give a 'administrative changes are not allowed in this environment' error.

The user manual entries are still accessible on dev environments.

Many thanks for your help

Installation Error

I'm getting a Composer was unable to install the updates due to a dependency conflict. when trying to install your plugin.

`Composer output: Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

Problem 1

• The requested package hillholliday/craft-user-manual could not be found in any version, there may be a typo in the package name.

Potential causes:

• A typo in the package name
• The package is not available in a stable-enough version according to your minimum-stability setting
  see for more details.
• It's a private package and you forgot to add a custom repository to find it

Read for further common problems.
Running update with --no-dev does not mean require-dev is ignored, it just means the packages will not be installed. If dev requirements are blocking the update you have to resolve those problems.`

New version not available in Updates

I have version 2.0.0 and would like to update to 2.0.1 to remove the deprecation errors but it doesn't show up as an update in Craft plugins. Do I have to do it through composer?

Toggle to disable front-end visibility of docs

First let me say, fantastic plugin! I've been using it for years and it's very reliable.

I actually came here to file this FR, and stumbled across a related thread that hit a lot of the same topics. In fact, this comment sums it all up...

The User Guide pages should not be accessible from the front-end of the site.

I guess it's cool that the data is accessible from the front-end, but I personally don't think I'd ever use it that way. If there was just a simple way to switch off the front-end visibility, that would be great.

I know we can add this snippet to our templates...

{%  if not currentUser %}
  {% redirect '/' %}
{% endif %}

... but that just feels like unnecessary clutter for something that should be handled automatically.

If you have to choose between #15 and this ticket, I would much rather you fix that ticket the way Daryl proposed. Like I said, I personally don't think I'd ever need to use this plugin to manage documentation on the front-end... there's no need for a toggle if you just kill off front-end access entirely.

Thanks for all your hard work! 🙂

Plans for Craft 3?

Interested if you have plans to port this to Craft 3.

There is https://github.com/wbrowar/craft-3-guide, but that takes quite a different, template-based approach.

Deprecation warnings

Thanks for porting it to Craft 3! There are several deprecation warnings showing in the CP for this plugin.

Users Can't Scroll Down

I have checked in Chrome, Firefox, & Safari on a Mac. I can't scroll down to view long guide pages. We are using the default template and just have the one rich text variable called "body." We can scroll down on when editing the guide pages but can't scroll down when viewing them as the content editors would be doing.

Plugin causes "Twig instantiated before Craft is fully initialized" warning

When I enable this plugin in Craft CMS v4.2.0.2 I get to see warnings telling me that Twig is instantiated too early (in the ./storage/logs/ directory or on the commandline when CRAFT_STREAM_LOG is active):

2022-08-03 11:32:08 [console.WARNING] [craft\web\View::createTwig] Twig instantiated before Craft is fully initialized. {"memory":22820336}

This seemed to be caused by the _addTwigExtensions() function that is called from the init-function in UserManual.php. This uses Craft::$app->view->twig->addExtension(new UserManualTwigExtension);, but according to https://craftcms.com/docs/4.x/extend/extending-twig.html#register-a-twig-extension should be Craft::$app->view->registerTwigExtension(new UserManualTwigExtension);

Would it be possible to fix this warning?

Is it possible to change admin url?

I have changed the working title of user manual to Admin Guide. Wondering if it is possible to change /admin/usermanual/{slug} to admin/admin-guide/{slug}
Thanks!

Suggestion - remove the requirement of URLs

To get a section to be usable for the User Manual, it must have URLs enabled. There are two downsides to this:

• http://domain.test/user-manual/entries resolves to the home page, because Craft resolves the template in Site Settings
• SEOmatic registers it as a section which needs Content SEO set up on it, which is irrelevant because it shouldn't be viewable on the front end.

Any chance of letting it somehow use a section which doesn't have URLs?

Update composer.json version to match tag

Small issue: the composer.json file for tag 2.0.1 has a version of 2.0.0.

⚠️ Please read: existing trouble, January 2022

Hey there,

I originally launched this plugin as open-source and I intend to keep it that way. Unfortunately I left my role at my previous job where I released this project. I am working with Pixel & Tonic to resolve the namespace issues across ID management and desire to provide continued support long-term. If there are any hiccups or issues you encounter implementing this plugin please let me know.

Thanks,
Rob

Not displaying any content

deleted - user error.

Feature request: add structure level indicator to admin

When using a structure as a source for the user manual, it would be nice to have a visual indicator of hierarchy for nested pages. Here's an example:

I have a pull request incoming which implements this.

Cannot install

When trying to install from the plugin store it results in a server timeout. When attempting from the command line it shows this error (Craft CMS 4.3.5):

In PackageDiscoveryTrait.php line 375:                                                                                                 
  Could not find a matching version of package roberskine/craft-user-manual. Check the package spelling, your version constraint and that the package is available in  
   a stability which matches your minimum-stability (stable).   

Deprecation errors

Following deprecation errors are occuring:

Looping through element queries directly has been deprecated. Use the all() function to fetch the query results before looping over them.
/Users/…/vendor/hillholliday/craft-user-manual/src/templates/index.twig:15

craft.request.getLastSegment() has been deprecated. Use craft.app.request.segments|last instead.
/Users/…/vendor/hillholliday/craft-user-manual/src/templates/index.twig:16

craft.config.get() has been deprecated. Use craft.app.config.general.setting instead.
/Users/…/vendor/hillholliday/craft-user-manual/src/templates/settings.twig:26

craft.config.get() has been deprecated. Use craft.app.config.general.setting instead.
/Users/…/vendor/hillholliday/craft-user-manual/src/templates/settings.twig:41

craft.config.get() has been deprecated. Use craft.app.config.general.setting instead.
/Users/…/vendor/hillholliday/craft-user-manual/src/templates/settings.twig:60

Does not show up in plugin list on case-sensitive environments

I've tried to install this plugin on a case-sensitive Apache environment, but it won't show up in the list of available plugins. I thought renaming "UserManual" to "usermanual" would work, but that did not seem to fix the issue either.