Document namespace feature

Author: Florens Verschelde

README.md

@@ -51,9 +51,10 @@ Documentation
 -------------
 
 -   [Twig templating guide](doc/templating.md)
+-   [Complete options documentation](doc/options.md)
 -   [How errors are displayed (or not)](doc/errors.md)
 -   [Using your own functions in templates](doc/functions.md)
--   [Complete options documentation](doc/options.md)
+-   [Twig support in Kirby plugins](doc/plugins.md)
 
 
 Credits

doc/errors.md

@@ -1,5 +1,5 @@
-kirby-twig: How errors are displayed (or not)
-=============================================
+[kirby-twig] How errors are displayed (or not)
+==============================================
 
 With PHP templates, most errors are shown directly in the page. Things are a bit different with Twig: if an error is not suppressed, the template will *not* be rendered at all, and you end up with an error page.
 
@@ -13,7 +13,7 @@ If `c::get('debug')` is true:
 - A nice error page is shown, with an excerpt of the faulty template code.
 
 <figure>
-    <img src="doc/errorpage.png" width="770" alt="">
+    <img src="errorpage.png" width="770" alt="">
 </figure>
 
 ## In production

doc/functions.md

@@ -1,5 +1,5 @@
-kirby-twig: Using your own functions in templates
-=================================================
+[kirby-twig] Using your own functions in templates
+==================================================
 
 
 If you need to expose PHP functions or classes to your Twig templates, you can list them with those two options:

doc/options.md

@@ -1,5 +1,7 @@
-kirby-twig: Options documentation
-=================================
+[kirby-twig] Options documentation
+==================================
+
+## Basic options
 
 ```php
 // REQUIRED: activate Twig plugin
@@ -12,12 +14,20 @@ c::set('twig.usephp', true);
 // Kirby URI of a page to render when there is a Twig error in production
 // For instance 'error/system'. Falls back to c::get('error').
 c::set('twig.error', '');
+```
+
+## Customizing the Twig environment
 
+```
 // List of additional functions that should be available in templates
 c::set('twig.env.functions', ['myCustomFunction']);
 
 // List of classes that can be instantiated from templates (with the `new()` function)
 c::set('twig.env.classes', ['SomeClass']);
+
+// Define a directory as a Twig namespace, that can be used as:
+//   {% include '@mynamespace/something.twig' %}
+c::set('twig.namespace.mynamespace', kirby()->roots()->index().'/mydirectory');
 ```
 
 ## Advanced

doc/plugins.md

@@ -0,0 +1,28 @@
+[kirby-twig] Twig support in Kirby plugins
+==========================================
+
+If you’re developing a Kirby plugin to share it with the Kirby community, it’s probably not a great idea to make it rely on kirby-twig. You should probably provide PHP templates or snippets.
+
+For project-specific plugins, though, if your project is using Twig, you might want to keep your plugin-related templates and snippets in your plugin’s folder. Here are a few config tricks that might help.
+
+```php
+<?php
+// site/myplugin/myplugin.php
+
+/**
+ * Add a Twig namespace for our plugin's templates
+ * Allows including with {% include '@myplugin/mytemplate.twig' %}
+ */
+c::set('twig.namespace.myplugin', __DIR__ . '/templates');
+
+/**
+ * Expose functions from our plugin to the Twig environment
+ */
+$twigFunctionNames = array_merge(
+    c::get('twig.env.functions', []),
+    ['myPluginFunction', 'myOtherFunction']
+);
+c::set('twig.env.functions', $twigFunctionNames);
+```
+
+See [Using your own functions in templates](functions.md) for more details about exposing functions, static methods and classes to templates.