📝 Add documentation for new z-index setting

README.md

@@ -119,6 +119,16 @@ Toggles the display of a side line showing which part of the buffer is currently
 
 When plugins are installed, a setting is created for each to enable/disable them directly from the Minimap settings view.
 
+#### Plugins * Decorations Z-Index
+
+When several plugins create decorations for the same layer, the general rule is to render the decorations as follows:
+
+- On the background layer, the `line` decorations are rendered before the `highlight-under` decorations.
+- On the foreground layer, the `highlight-over` decorations are rendered before the `highlight-outine` decorations.
+- When two plugins adds the same type of decorations at the same place, the decorations are rendered in the order they have been created.
+
+But fortunately, it's possible to reorder decorations on their specific layer using these settings. These settings works as a `z-index` in CSS, the higher the value, the higher the decorations will be in the render stack, for instance, a plugin's decorations with an order value of `1` will appear above decorations from a plugin with an order value of `0`.
+
 #### Smooth Scrolling
 
 Whether to offset the minimap canvas when scrolling to keep the scroll smooth. When `true` the minimap canvas will be offseted, resulting in a smoother scroll, but with the side-effect of a blurry minimap when the canvas is placed between pixels. When `false` the canvas will always stay at the same position, and will never look blurry, but the scroll will appear more jagged. `(default=true)`
@@ -368,6 +378,14 @@ minimapView.decorateMarker(marker, {type: 'line', color: '#ff0000'})
 
 In that case neither the scope nor the class will be used.
 
+#### Decorations Origin
+
+A plugin can and should set the plugin origin on the decorations it creates so that the Minimap can easily know which order to apply on the decorations. When not provided, the plugin origin will be inferred from the path of the function invoking the `decorateMarker` method. If the origin can't be inferred the order value will always be `0` for this decoration.
+
+```js
+minimapView.decorateMarker(marker, {type: 'line', color: '#ff0000', plugin: 'my-plugin-name'})
+```
+
 #### Decorations Types
 
 Another non-trivial change is the list of available decoration's type. At the time, the available types on the Minimap are:

lib/mixins/decoration-management.js

@@ -293,9 +293,17 @@ export default class DecorationManagement extends Mixin {
    *                                        decoration background. Note that if
    *                                        the `scope` property is set, the
    *                                        `class` won't be used.
-   * @param  {string} [decorationParams.color] the CSS color to use to render the
-   *                                        decoration. When set, neither
-   *                                        `scope` nor `class` are used.
+   * @param  {string} [decorationParams.color] the CSS color to use to render
+   *                                           the decoration. When set, neither
+   *                                           `scope` nor `class` are used.
+   * @param  {string} [decorationParams.plugin] the name of the plugin that
+   *                                            created this decoration. It'll
+   *                                            be used to order the decorations
+   *                                            on the same layer and that are
+   *                                            overlapping. If the parameter is
+   *                                            omitted the Minimap will attempt
+   *                                            to infer the plugin origin from
+   *                                            the path of the caller function.
    * @return {Decoration} the created decoration
    * @emits  {did-add-decoration} when the decoration is created successfully
    * @emits  {did-change} when the decoration is created successfully