Initial Askama Book (#332)

1 files changed, 93 insertions, 0 deletions

diff --git a/book/src/creating_templates.md b/book/src/creating_templates.md
new file mode 100644
index 0000000..406a825
--- /dev/null
+++ b/book/src/creating_templates.md
@@ -0,0 +1,93 @@
+# Creating Templates
+
+An Askama template is a `struct` definition which provides the template
+context combined with a UTF-8 encoded text file (or inline source, see
+below). Askama can be used to generate any kind of text-based format.
+The template file's extension may be used to provide content type hints.
+
+A template consists of **text contents**, which are passed through as-is,
+**expressions**, which get replaced with content while being rendered, and
+**tags**, which control the template's logic.
+The [template syntax](template_syntax.md) is very similar to [Jinja](http://jinja.pocoo.org/),
+as well as Jinja-derivatives like [Twig](http://twig.sensiolabs.org/) or
+[Tera](https://github.com/Keats/tera).
+
+```rust
+#[derive(Template)] // this will generate the code...
+#[template(path = "hello.html")] // using the template in this path, relative
+                                 // to the `templates` dir in the crate root
+struct HelloTemplate<'a> { // the name of the struct can be anything
+    name: &'a str, // the field name should match the variable name
+                   // in your template
+}
+```
+
+## The `template()` attribute
+
+Askama works by generating one or more trait implementations for any
+`struct` type decorated with the `#[derive(Template)]` attribute. The
+code generation process takes some options that can be specified through
+the `template()` attribute. The following sub-attributes are currently
+recognized:
+
+* `path` (as `path = "foo.html"`): sets the path to the template file. The
+  path is interpreted as relative to the configured template directories
+  (by default, this is a `templates` directory next to your `Cargo.toml`).
+  The file name extension is used to infer an escape mode (see below). In
+  web framework integrations, the path's extension may also be used to
+  infer the content type of the resulting response.
+  Cannot be used together with `source`.
+  ```rust
+  #[derive(Template)]
+  #[template(path = "hello.html")]
+  struct HelloTemplate<'a> { ... }
+  ```
+
+* `source` (as `source = "{{ foo }}"`): directly sets the template source.
+  This can be useful for test cases or short templates. The generated path
+  is undefined, which generally makes it impossible to refer to this
+  template from other templates. If `source` is specified, `ext` must also
+  be specified (see below). Cannot be used together with `path`.
+  ```rust
+  #[derive(Template)]
+  #[template(source = "Hello {{ name }}")]
+  struct HelloTemplate<'a> {
+      name: &'a str,
+  }
+  ```
+* `ext` (as `ext = "txt"`): lets you specify the content type as a file
+  extension. This is used to infer an escape mode (see below), and some
+  web framework integrations use it to determine the content type.
+  Cannot be used together with `path`.
+  ```rust
+  #[derive(Template)]
+  #[template(source = "Hello {{ name }}", ext = "txt")]
+  struct HelloTemplate<'a> {
+      name: &'a str,
+  }
+  ```
+* `print` (as `print = "code"`): enable debugging by printing nothing
+  (`none`), the parsed syntax tree (`ast`), the generated code (`code`)
+  or `all` for both. The requested data will be printed to stdout at
+  compile time.
+  ```rust
+  #[derive(Template)]
+  #[template(path = "hello.html", print = "all")]
+  struct HelloTemplate<'a> { ... }
+  ```
+* `escape` (as `escape = "none"`): override the template's extension used for
+  the purpose of determining the escaper for this template. See the section
+  on configuring custom escapers for more information.
+  ```rust
+  #[derive(Template)]
+  #[template(path = "hello.html", escape = "none")]
+  struct HelloTemplate<'a> { ... }
+  ```
+* `syntax` (as `syntax = "foo"`): set the syntax name for a parser defined
+  in the configuration file. The default syntax , "default",  is the one
+  provided by Askama.
+  ```rust
+  #[derive(Template)]
+  #[template(path = "hello.html", syntax = "foo")]
+  struct HelloTemplate<'a> { ... }
+  ```
\ No newline at end of file