Open source CMS Guide templates for use in the Guide plugin for Craft CMS.

Guide is made up of two parts:

• The commercial plugin for Craft 3
• The open source user Guide template

If you are looking for templates for Guide 1, see the guide-1 branch of this repo.

The Guide plugin for Craft 3 is built so you can drop in a CMS Guide template and tailor it to your client’s website. Craft Guide Templates is meant to give you a starting point and to offer inspiration and examples for your company’s boilerplate Guide template.

While these template files and assets are created to support the commercial Guide plugin, they are open and free to use however you’d like. They are like the penny jar for CMS guides: if you need an idea, take one, and if you have an idea, please consider contributing.

These Guide templates can be added to a Craft website in one of two ways:

The simplest way is to import templates from within Guide’s General Settings page. Clicking on the "Download Templates" button will download this repository to your site’s storage directory, unzip it, and present you with a list of importable templates.

Clicking on which parts of a Guide template you’d like to import, then clicking on the "Import" button will move template files and assets into the right directories.

Once assets are imported, you may have to run Craft’s "Update asset indexes" command to make sure assets are added to your Guide Asset Volume.

Clicking on the "Import Guides into Organizer" option will not move any files, but it will add guides into the database. Imported guides will appear in the "Unused Guides" column of the Guide Organizer.

Adding a path into Guide’s Template Path setting will let Guide know where to look for Guide templates within your site’s templates directory.

To manually add templates from this repo into your site, follow these steps:

1. Download this repo and unzip it onto your server.
2. Move the template files of your choice from the unzipped directory into your Guide Template Path (./templates/_guide by default).
3. In Craft’s CP, visit the Guide Organizer and click the "+ New Guide" button to create a new guide.
4. Set a title and any other guide options you’d like. Select Page Template from the Content Source field.
5. Select a Guide template for the Template field and click "Save".

If you have something you'd like to add to a Guide template, if you find a typo you’d like to fix, or if you're a plugin developer who can help write an official how-to, please do so in the form of a Pull Request.

If you would like to create a new Guide template and add it to this repo, please follow these steps:

1. Create a new folder in the appropriate language folder (create a new language folder if needed).
2. In that folder, create an info.json file and fill it out using the options in the Info File section, below.
3. In ./GUIDES.json add the path to your guide to the list of paths.
4. If your Guide template requires assets, create an assets folder, add your assets there, and add the path to the folder into your info.json file. NOTE: The path should be relative to the root of this repo.
5. Create a templates folder, create your .md, .twig, or .html files in this new folder, and add the path to the folder into your info.json file. NOTE: This path should also be relative to the root of this repo.
6. In your info.json file, add a guides array and add information required for each of the templates in your guide.
7. Submit your new Guide template via pull request.

The info.json file provides Guide with information necessary for importing your template files and assets.

The objects in the guides array can use the following properties:

Twig-based guides are rendered with all of Craft’s Twig functions and filters, so specific information can safely be added to a Twig-based Guide template based on whether or not a plugin is installed onto a reader’s website.

To add information about your plugin to a Guide template, please follow these best practices:

• Use Craft’s plugin Twig function to encapsulate information specific to your plugin. For example, {% if plugin('guide') %}<p>Here’s how you use Guide.</p>{% endif %}
  • This will check to see if your plugin is installed and enabled. If not, the information will not be displayed.
• Write information in a similar tone and with similar language to the rest of the Guide template.
• Information that is more technical in nature should be included within a check to see if the user is an admin (currentUser.admin). This assumes that an admin is the developer of the website or a person familiar with the technical aspects of the website.
• Information can be written for users with specific permissions, by checking currentUser.can('REPLACE_PERMISSION_KEY').
• If you’d like to embed your plugin’s docs as an iframe, add a new object into the Guide template’s info.json file’s guides array. This object should look something like this:

{
    "contentSource": "iframe",
    "contentUrl": "https://docs.craftcms.com/v3/",
    "slug": "craft-docs",
    "title": "Craft Docs"
}

NOTE: All contributions may be edited or rejected if it falls outside of the scope described in the Guide template’s info.json, if its content is inappropriate, or if it is reported as incorrect information.