Opt-in features

Some features in askama are opt-in to reduce the amount of dependencies, and to keep the compilation time low.

To opt-in to a feature, you can use features = […]. E.g. if you want to use the filter |json, you have to opt-in to the feature "serde_json":

[dependencies]
askama = { version = "0.14.0", features = ["serde_json"] }

Please read the Cargo manual for more information.

Default features

Any semver-compatible upgrade (e.g. askama = "0.14.1" to askama = "0.14.2") will keep the same list of default features. We will treat upgrades to a newer dependency version as a semver breaking change.

"default"

You can opt-out of using the feature flags by using default-features = false:

[dependencies]
askama = { version = "0.14.0", default-features = false }

Without default-features = false, i.e with default features enabled, the following features are automatically selected for you:

default = ["config", "derive", "std", "urlencode"]

This should encompass most features an average user of askama might need.

If you are writing a library that depends on askama, and if you want it to be usable in by other users and in other projects, then you should probably opt-out of features you do not need.

"derive"

enabled by "default"

This feature enables #[derive(Template)]. Without it the trait askama::Template will still be available, but if you want to derive a template, you have to manually depend on askama_macros. askama_macros should be used with the same features as askama.

Not using this feature might be useful e.g. if you are writing a library with manual filters for askama, without any templates. It might also very slightly speed-up the compilation, because more dependencies can be compiled in parallel, because askama won't transitively depend on e.g. syn or proc-macro2. On the author's PC the compilation of a trivial hello-world example was about 0.2s faster without the feature when compiled in release mode.

If you are writing a library that uses askama, consider not using this default-feature.

"config"

enabled by "default"

Enables compile time configurations.

"urlencode"

enabled by "default"

Enables the filters |urlencode and |urlencode_strict.

Addition features

The most useful catch-all feature for a quick start might be "full", which enables all implemented features, i.e.:

full = ["default", "blocks", "code-in-doc", "serde_json"]

In production or once your project is “maturing” you might want to manually opt-in to any needed features with a finer granularity instead of depending on "full".

"blocks"

enabled by "full"

Enables using the template attribute blocks.

"serde_json"

enabled by "full"

Enables the filter |json.

"code-in-doc"

enabled by "full"

Enables using documentations as template code.

“Anti-features” in a #![no_std] environment

Opting-out of the default features "std" and "alloc" is only interesting for the use in a #![no_std] environment. Please find more information in The Embedded Rust Book.

"alloc"

enabled by "default"

Without the default feature "alloc" askama can be used in a #![no_std] environment. The method Template::render() will be absent, because askama won't have access to a default allocator.

Many filters need intermediate allocations, and won't be usable without this feature.

You can still render templates using e.g. no_std_io2::io::Cursor or embedded_io::Write

"std"

enabled by "default"

Without the feature "std" askama can be used in a #![no_std] environment. The method Template::write_into() will be absent, because askama won't have access to standard IO operations.

Enabling "std" enables "alloc", too.