Editable with ContentTools Plugin
The Editable with ContentTools Plugin is for Grav CMS.
The plugin allows authors to edit page content in the frontend using the WYSIWYG editor ContentTools and save it as Markdown.
This may limit its use case depending on your requirements.
Please visit the ContentTools website for tips on using the ContentTools editor, like holding down the Shift key for about 3 seconds to see what regions on the page are editable (tip!).
Typically the plugin should be installed via GPM (Grav Package Manager):
$ bin/gpm install editable-contenttools
Or you can manualy install it by downloading the plugin as a zip file. Copy the zip file to your
/user/plugins directory, unzip it there and rename the folder to
Before configuring this plugin, you should copy the
Make configuration changes to that copy so your changes will be kept when installing a new version of the plugin.
Alternatively the plugin can be installed via the Admin Plugin. When using the Admin Plugin there is no need to copy the configuration files manually.
Here is the default configuration and an explanation of available options:
enabled: true git-sync: false git-sync-mode: foreground
true enables or activates the plugin.
true and the Git Sync plugin is installed and enabled, every save action triggers a Git Sync synchronisation.
git-sync-mode setting defaults to
foreground where the plugin halts until the synchronisation is finished before control is handed back to the user. When set to
background the sync is unobtrusive to the user.
Note: background syncing on Linux systems is not guaranteed to work and has currently not been tested on a Windows server. Feedback is welcome!
Possibly limited use case
This plugin works on plain simple Markdown only. This limits the use case but is a consequence of the conversion of Markdown to HTML and back again.
Just to set expectations right please note that this plugin will not work on a page or on content which:
- is processed by a Twig template, for example modulars
- is injected by plugins, for example the Page Inject Plugin
and will corrupt special Grav Markdown tags such as:
There are some simple rules to keep on the safe side:
- Keep images and other shortcodes outside your editable regions
- Create small editable regions; it does not matter how many
- Experiment and test to make sure it works for you and you don't lose valuable content
- When you notice a difference in markup of the page with the ContentTools pen icon present and without keep that part of the page outside of your editable regions, it means trouble is ahead ;)
The shortcode [editable]
Page content that may be edited in the frontend should be marked by using the shortcode
[editable] # Chapter 1 Once upon a time ... [/editable]
A page may contain any number of such editable regions.
Shortcode name parameter (optional)
For the ContentTools editor to work every editable region in a page must be uniquely identified by a 'name' parameter. Optionally you can give each shortcode a name which must be unique within the page.
The name parameter is optional. When non or an empty shortcode name parameter is present the plugin assigns names like "region-x" where x is a sequential increasing number.
[editable name="region-0"] Once upon a time ... [/editable]
To be able to save changed content back into the right regions the names need to be present in the page content and are therefor automatically saved in the page.
To enable users to edit content in the frontend they must be able to login.
To edit a page a frontend user must have the permission
site.editable. Add the required authorization to each user in the user's account file:
access: site: login: 'true' editable: 'true'
By default Grav separates backend (Admin) and frontend users into separate sessions.
Allowing backend users to edit pages in the frontend requires the Grav option
session.split to be set to
system.yaml or in the Admin panel).
A backend or Admin user must have the permission
admin.pages to be allowed to edit a page.
Thanks go to:
- The Grav Core Team for creating Grav
- getme for creating ContentTools
- Dom Christie for creating Turndown
- Paul Hibbits of Hibbits Design for testing and feedback
- Everyone on the Grav Forum for supporting Grav
[ ] Add file upload
[ ] Add superscript and subscript tools
[ ] Think about handling images
BTW all the above to do's require custom ContentTools tools and I don't have a clue how to create one...