diff --git a/docs/en/topics/rich-text-editing.md b/docs/en/topics/rich-text-editing.md
index 8a17c848e..d4549a750 100644
--- a/docs/en/topics/rich-text-editing.md
+++ b/docs/en/topics/rich-text-editing.md
@@ -9,8 +9,8 @@ you can effectively select and upload files.
## Usage
-The framework comes with a `[api:HTMLEditorField]` form field class which encapsulates most of the required functionality.
-It is usually added through the `[api:DataObject->getCMSFields()]` method:
+The framework comes with a `[api:HTMLEditorField]` form field class which encapsulates most of the required
+functionality. It is usually added through the `[api:DataObject->getCMSFields()]` method:
:::php
class MyObject extends DataObject {
@@ -27,25 +27,130 @@ To keep the JavaScript editor configuration manageable and extensible,
we've wrapped it in a PHP class called `[api:HtmlEditorConfig]`.
The class comes with its own defaults, which are extended through the `_config.php`
files in the framework (and the `cms` module in case you've got that installed).
-There can be multiple configs, which should always be created / accessed using `[api:HtmlEditorConfig::get].
-You can then set the currently active config using `set_active()`.
+There can be multiple configs, which should always be created / accessed using `[api:HtmlEditorConfig::get]`.
+You can then set the currently active config using `set_active()`.
By default, a config named 'cms' is used in any field created throughout the CMS interface.
-Example: Enable the "media" plugin:
+
+Caveat: currently the order in which the `_config.php` files are executed depends on the module directory
+names. Execution order is alphabetical, so if you set a TinyMCE option in the `aardvark/_config.php`, this
+will be overriden in `framework/admin/_config.php` and your modification will disappear.
+
+This is a general problem with `_config.php` files - it may be fixed in the future by making it possible to
+configure the TinyMCE with the new [configuration system](../topics/configuration).
+
+
+### Adding and removing capabilities
+
+In its simplest form, the configuration of the editor includes adding and removing buttons and plugins.
+
+You can add plugins to the editor using the Framework's `[api:HtmlEditorConfig::enablePlugins]` method. This will
+transparently generate the relevant underlying TinyMCE code.
:::php
// File: mysite/_config.php
HtmlEditorConfig::get('cms')->enablePlugins('media');
-Example: Remove some buttons for more advanced formatting
+Note: this utilises the TinyMCE's `PluginManager::load` function under the hood (check the
+[TinyMCE documentation on plugin
+loading](http://www.tinymce.com/wiki.php/API3:method.tinymce.AddOnManager.load) for details).
+
+Plugins and advanced themes can provide additional buttons that can be added (or removed) through the
+configuration. Here is an example of adding a `ssmacron` button after the `charmap` button:
+
+ :::php
+ // File: mysite/_config.php
+ HtmlEditorConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron');
+
+Buttons can also be removed:
:::php
// File: mysite/_config.php
HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');
+Note: internally `[api:HtmlEditorConfig]` uses the TinyMCE's `theme_advanced_buttons` option to configure these. See
+the [TinyMCE documentation of this option](http://www.tinymce.com/wiki.php/Configuration:theme_advanced_buttons_1_n)
+for more details.
+
+### Setting options
+
+TinyMCE behaviour can be affected through its [configuration options](http://www.tinymce.com/wiki.php/Configuration).
+These options will be passed straight to the editor.
+
+One example of the usage of this capability is to redefine the TinyMCE's [whitelist of HTML
+tags](http://www.tinymce.com/wiki.php/Configuration:extended_valid_elements) - the tags that will not be stripped
+from the HTML source by the editor.
+
+ :::php
+ // Add start and type attributes for , add