<commit_before>+++
template = "docs.html"
insert_anchor_links = "right"
+++

# Getting started

To use Tera in your Rust projects, simply add it to your `Cargo.toml`:

```toml
tera = "1"
```

By default, Tera comes with some additional dependencies required for the `truncate`, `date`, `filesizeformat`, `slugify`, `urlencode` and `urlencode_strict` filters as
well as for the `now` function. You can disable them by setting the following in your `Cargo.toml`:

```toml
[dependencies.tera]
version = "1"
default-features = false
```


And add the following to your `lib.rs` or `main.rs` if you are not using Rust 2018 edition or later:

```rs
extern crate tera;
```

You can view everything Tera exports on the [API docs](https://docs.rs/tera).

# Usage

The primary method of using Tera is to load and parse all the templates in a given glob.

Let's take the following directory as example.

```sh
templates/
  hello.html
  index.html
  products/
    product.html
    price.html
```

Assuming the Rust file is at the same level as the `templates` folder, we can get a Tera instance that way:

```rs
use tera::Tera;

// Use globbing
let tera = match Tera::new("templates/**/*.html") {
    Ok(t) => t,
    Err(e) => {
        println!("Parsing error(s): {}", e);
        ::std::process::exit(1);
    }
};
```

Compiling templates is a step that is meant to only happen once: use something like [lazy_static](https://crates.io/crates/lazy_static)
to define a constant instance.

```rs
lazy_static! {
    pub static ref TEMPLATES: Tera = {
        let mut tera = match Tera::new("examples/basic/templates/**/*") {
            Ok(t) => t,
            Err(e) => {
                println!("Parsing error(s): {}", e);
                ::std::process::exit(1);
            }
        };
        tera.autoescape_on(vec!["html", ".sql"]);
        tera.register_filter("do_nothing", do_nothing_filter);
        tera
    };
}
```

You need two things to render a template: a name and a context.
If you are using globs, Tera will automatically remove the glob prefix from the template names. To use our example from before,
the template name for the file located at `templates/hello.html` will be `hello.html`.

The context can either be a data structure that implements the `Serialize` trait from `serde_json` or an instance of `tera::Context`:

```rs
use tera::Context;
// Using the tera Context struct
let mut context = Context::new();
context.insert("product", &product);
context.insert("vat_rate", &0.20);
tera.render("products/product.html", &context)?;

#[derive(Serialize)]
struct Product {
    name: String
}
// or a struct
tera.render("products/product.html", &Context::from_serialize(&product)?)?;
```

## Auto-escaping
By default, Tera will auto-escape all content in files ending with `".html"`, `".htm"` and `".xml"`.<commit_msg>Fix HTML file extension in auto-escaping example (#697)<commit_after>+++
template = "docs.html"
insert_anchor_links = "right"
+++

# Getting started

To use Tera in your Rust projects, simply add it to your `Cargo.toml`:

```toml
tera = "1"
```

By default, Tera comes with some additional dependencies required for the `truncate`, `date`, `filesizeformat`, `slugify`, `urlencode` and `urlencode_strict` filters as
well as for the `now` function. You can disable them by setting the following in your `Cargo.toml`:

```toml
[dependencies.tera]
version = "1"
default-features = false
```


And add the following to your `lib.rs` or `main.rs` if you are not using Rust 2018 edition or later:

```rs
extern crate tera;
```

You can view everything Tera exports on the [API docs](https://docs.rs/tera).

# Usage

The primary method of using Tera is to load and parse all the templates in a given glob.

Let's take the following directory as example.

```sh
templates/
  hello.html
  index.html
  products/
    product.html
    price.html
```

Assuming the Rust file is at the same level as the `templates` folder, we can get a Tera instance that way:

```rs
use tera::Tera;

// Use globbing
let tera = match Tera::new("templates/**/*.html") {
    Ok(t) => t,
    Err(e) => {
        println!("Parsing error(s): {}", e);
        ::std::process::exit(1);
    }
};
```

Compiling templates is a step that is meant to only happen once: use something like [lazy_static](https://crates.io/crates/lazy_static)
to define a constant instance.

```rs
lazy_static! {
    pub static ref TEMPLATES: Tera = {
        let mut tera = match Tera::new("examples/basic/templates/**/*") {
            Ok(t) => t,
            Err(e) => {
                println!("Parsing error(s): {}", e);
                ::std::process::exit(1);
            }
        };
        tera.autoescape_on(vec![".html", ".sql"]);
        tera.register_filter("do_nothing", do_nothing_filter);
        tera
    };
}
```

You need two things to render a template: a name and a context.
If you are using globs, Tera will automatically remove the glob prefix from the template names. To use our example from before,
the template name for the file located at `templates/hello.html` will be `hello.html`.

The context can either be a data structure that implements the `Serialize` trait from `serde_json` or an instance of `tera::Context`:

```rs
use tera::Context;
// Using the tera Context struct
let mut context = Context::new();
context.insert("product", &product);
context.insert("vat_rate", &0.20);
tera.render("products/product.html", &context)?;

#[derive(Serialize)]
struct Product {
    name: String
}
// or a struct
tera.render("products/product.html", &Context::from_serialize(&product)?)?;
```

## Auto-escaping
By default, Tera will auto-escape all content in files ending with `".html"`, `".htm"` and `".xml"`.
{'fraction_non_alphanumeric': 0.13523943167865288, 'fraction_numerical': 0.004385195579722855, 'mean_word_length': 3.5909822866344605, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5688982', 'n_tokens_mistral': 1817, 'n_tokens_neox': 1741, 'n_words': 656}