Add doc for Ace templates

Fixes #1063

diff --git a/docs/content/templates/ace.md b/docs/content/templates/ace.md
new file mode 100644 (file)
index 0000000..3f96b96
--- /dev/null
+++ b/docs/content/templates/ace.md
@@ -0,0 +1,66 @@
+---
+aliases:
+- /doc/templates/ace
+- /layout/templates/ace
+- /layout/ace/
+date: 2014-04-20
+linktitle: Ace templates
+menu:
+  main:
+    parent: layout
+next: /templates/functions
+prev: /templates/go-templates
+title: Hugo Templates
+weight: 17
+---
+
+In addition to [Go templates](/templates/go-templates) and Amber[^needs-doc] templates, Hugo supports the powerful Ace templates.
+
+For template documentation, follow the links from the [Ace project](https://github.com/yosssi/ace). 
+
+* Ace templates must be named with the ace-suffix, e.g. `list.ace`
+* It's possible to use both Go templates and Ace templates side-by-side, and include one into the other
+* Full Go template syntax support, including all the useful helper funcs
+* Partials can be included both with the Ace and the Go template syntax:
+       * `= include partials/foo.html .`[^ace-theme]
+       * `{{ partial "foo" . }}`
+
+
+One noticable difference between Ace and the others is the inheritance support through [base and inner templates](https://github.com/yosssi/ace/tree/master/examples/base_inner_template).
+
+In Hugo the base template will be chosen in the following order:
+
+```
+1. <current-path>/<template-name>-baseof.ace, e.g. list-baseof.ace
+2. <current-path>/baseof.ace
+3. _default/<template-name>-baseof.ace, e.g. list-baseof.ace.
+4. _default/baseof.ace 
+```
+
+In the above, `current-path` is where the corresponding inner template lives, `list.ace`, `single.ace`, `index.ace` ...
+
+```
+.:
+index.ace
+
+./blog:
+single.ace
+baseof.ace
+
+./_default:
+baseof.ace  list.ace  single.ace  single-baseof.ace
+```
+
+Some examples for the layout files above:
+
+* Home page: `./index.ace` +  `./_default/baseof.ace` 
+* Single page in the `blog` section: `./blog/single.ace` +  `./blog/baseof.ace`
+* Single page in another section: `./_default/single.ace` +  `./_default/single-baseof.ace`
+* Taxonomy page in any section: `./_default/list.ace` +  `./_default/baseof.ace`
+
+**Note:** An Ace template without a reference to a base secion, e.g. `= content`, will be handled as a standalone template.
+
+
+[^ace-theme]: Note that the `html` suffix is needed, even if the filename is suffixed `ace`. This does not work from inside a theme, see [issue 763](https://github.com/spf13/hugo/issues/763).
+[^needs-doc]: Needs documentation! Contribution welcomed, see [issue 1064](https://github.com/spf13/hugo/issues/1064).
+

diff --git a/docs/content/templates/go-templates.md b/docs/content/templates/go-templates.md
index c36f2a843b3c025df42ffd141b1e0599b257089a..adb1ae3c9d8154cc91a22c4d213eeec13fd4dae3 100644 (file)
--- a/docs/content/templates/go-templates.md
+++ b/docs/content/templates/go-templates.md
@@ -6,7 +6,7 @@ date: 2013-07-01
 menu:
   main:
     parent: layout
-next: /templates/functions
+next: /templates/ace
 prev: /templates/overview
 title: Go Template Primer
 weight: 15