Improve docs for plugins

1 files changed, 62 insertions, 0 deletions

diff --git a/docs/plugins/blocks.md b/docs/plugins/blocks.md
new file mode 100644
index 0000000..6fc227b
--- /dev/null
+++ b/docs/plugins/blocks.md
@@ -0,0 +1,62 @@
+# Extend Blocks
+
+Extending templating blocks is the best way to provide extra functionalities to authors.
+
+The most common usage is to process the content within some tags at runtime. It's like [filters](./filters.md), but on steroids because you aren't confined to a single expression.
+
+### Defining a new block
+
+Blocks are defined by the plugin, blocks is a map of name associated with a block descriptor. The block descriptor needs to contain at least a `process` method.
+
+```js
+module.exports = {
+    blocks: {
+        tag1: {
+            process: function(block) {
+                return "Hello "+block.body+", How are you?";
+            }
+        }
+    }
+};
+```
+
+The `process` should return the html content that will replace the tag. Refer to [Context and APIs](./api.md) to learn more about `this` and GitBook API.
+
+### Handling block arguments
+
+Arguments can be passed to blocks:
+
+```
+{% tag1 "argument 1", "argument 2", name="Test" %}
+This is the body of the block.
+{% endtag1 %}
+```
+
+And arguments are easily accessible in the `process` method:
+
+```js
+module.exports = {
+    blocks: {
+        tag1: {
+            process: function(block) {
+                // block.args equals ["argument 1", "argument 2"]
+                // block.kwargs equals { "name": "Test" }
+            }
+        }
+    }
+};
+```
+
+### Handling sub-blocks
+
+A defined block can be parsed into different sub-blocks, for example let's consider the source:
+
+```
+{% myTag %}
+    Main body
+    {% subblock1 %}
+    Body of sub-block 1
+    {% subblock 2 %}
+    Body of sub-block 1
+{% endmyTag %}
+```