Move the directive documentation into its own underlay, separate from basewiki,...

[ikiwiki.git] / doc / ikiwiki / directive / edittemplate.mdwn

diff --git a/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn
new file mode 100644 (file)
index 0000000..b3187ea
--- /dev/null
+++ b/doc/ikiwiki/directive/edittemplate.mdwn
@@ -0,0 +1,34 @@
+The `edittemplate` directive is supplied by the [[!iki plugins/edittemplate]] plugin.
+
+This directive allows registering template pages, that provide default
+content for new pages created using the web frontend. To register a
+template, insert a [[ikiwiki/directive/template]] directive on some other page.
+
+       \[[!edittemplate template="bugtemplate" match="bugs/*"]]
+
+In the above example, the page named "bugtemplate" is registered as a
+template to be used when any page named "bugs/*" is created.
+
+Often the template page contains a simple skeleton for a particular type of
+page. For the bug report pages in the above example, it might look
+something like:
+
+       Package: 
+       Version: 
+       Reproducible: y/n
+       Details:
+
+The template page can also contain [[!cpan HTML::Template]] directives,
+similar to other ikiwiki [[templates]]. Currently only one variable is
+set: `<TMPL_VAR name>` is replaced with the name of the page being
+created.
+
+----
+
+It's generally not a good idea to put the `edittemplate` directive in
+the template page itself, since the directive would then be included as
+part of the template on new pages, which would then in turn be registered
+as templates. If multiple pages are registered as templates for a new page,
+an arbitrary one is chosen, so that could get confusing.
+
+[[!meta robots="noindex, follow"]]