Changing a template’s rendering engine docs.

README.md

@@ -29,6 +29,7 @@ Works with:
 
 ### Read More at:
 
+* [Changing a Template’s Rendering Engine](docs/engines.md)
 * [Collections](docs/collections.md), grouping content together
 * [Common Pitfalls](docs/pitfalls.md)
 * [Custom Filters, Helpers, Tags](docs/filters.md)

docs/data.md

@@ -24,6 +24,7 @@ Here are a few special front matter keys you can use:
 * `pagination`: Enable to iterate over data. Output multiple HTML files from a single template. [Read more about Pagination](pagination.md).
 * `tags`: A single string or array that identifies that a piece of content is part of a collection. Collections can be reused in any other template. [Read more about Collections](collections.md).
 * `date`: Override the default date (file creation) to customize how the file is sorted in a collection. [Read more about Collections](collections.md).
+* `templateEngineOverride`: Override the template engine on a per-file basis, usually configured with a file extension or globally using the `markdownTemplateEngine` and `htmlTemplateEngine` configuration options. [Read more about Changing a Template’s Rendering Engine](engines.md).
 
 ## External Data Files
 

docs/engines.md

@@ -0,0 +1,55 @@
+# Changing a Template’s Rendering Engine
+
+_New in Eleventy `v0.2.14`_ There are a couple of different ways you can tell Eleventy how you want to process a file:
+
+1. The file extension (importantly, this is also used to find files to process).
+2. [Configuration options](../README.md#configuration-optional)
+
+* `markdownTemplateEngine`: The default global template engine to pre-process markdown files. Use `false` to avoid pre-processing and only transform markdown.
+* `htmlTemplateEngine`: The default global template engine to pre-process HTML files. Use `false` to avoid pre-processing and passthrough copy the content (HTML is not transformed, so technically this could be any plaintext).
+
+3. `templateEngineOverride` in the template’s front matter. Should be _one_ templating engine (`liquid`) or markdown paired with another templating engine (`liquid,md`). See examples below.
+
+## `templateEngineOverride` Examples
+
+### Replace with a single templating engine
+
+If your file is called `example.liquid`—instead of `liquid`, this will be parsed as a `njk` Nunjucks template:
+
+```
+---
+templateEngineOverride: njk
+---
+```
+
+### Special case: pairing a templating engine with `md` Markdown
+
+Remember that—by default—Markdown files are processed with an additional preprocessor template engine set globally with the `markdownTemplateEngine` configuration option. So, when using `templateEngineOverride` on markdown files be sure to list each templating engine you’d like to use.
+
+For example, you may want to process `njk` Nunjucks first and then `md` markdown afterwards. Markdown is supported either by itself or with another engine. No other templating engines can be combined in this way—Markdown is the exception here. Any other combination attempt will throw an error.
+
+#### Markdown and nothing else
+
+```
+---
+templateEngineOverride: md
+---
+```
+
+#### Nunjucks and then Markdown
+
+```
+---
+templateEngineOverride: njk,md
+---
+```
+
+### Use nothing (no transformations)
+
+Any falsy value here will just copy the template content without transformation.
+
+```
+---
+templateEngineOverride: false
+---
+```