1 files changed, 32 insertions, 1 deletions
diff --git a/README.md b/README.md
index 068c1fa..9a2ba59 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,38 @@ name = "John Doe"
 email = "john@example.com"
 ```
 
-## Lua scripting
+## Lua templates
+
+You can define Lua functions in `.lua` files within the `modules/` directory
+and then call them within `.md` files using the `{{modulename.functionname}}`
+syntax. For example if you create `modules/example.lua` with:
+
+```lua
+function greet(args)
+    return 'Hello ' .. args[1] .. '!'
+end
+
+function sum(args)
+    return args.x + args.y
+end
+
+return {greet=greet, sum=sum}
+```
+
+within Markdown files `{{example.greet|world}}` will become
+`Hello world!` and `{{example.sum|x=3|y=5}}` will become 8.
+
+Note that:
+
+* If no module name is given it defaults to `default` so e.g. `{{foo}}`
+  will attempt to call the `foo` function defined in `modules/default.lua`.
+* In order to pass `|` or `}}` within arguments you need to
+  escape them by prefixing a slash e.g. `{{foo| \| \}} }}`.
+* Within `<pre>` and `<raw>` tags and HTML comments no special syntax is interpreted.
+* Note that none of these constructs can be nested. E.g. `{{foo|{{bar}} }}` or
+  `{{foo|<raw>test</raw>}}` will not work as you might expect.
+
+## Lua shebangs
 
 Files can start with a shebang like `#!hello`, which will
 interpret the following text with the `view` function returned