Stilts is a templating language inspired by Askama. That means it features all the type safety the rust compiler will give you. It is still loosly related to Jinja, however it has adopted a more rust-like expression syntax.
I started this project because rust is a great language, and Jinja2 is the template engine I was most used to. I however felt that one thing Jinja always lacked was expressivity, in the sense that you couldn't write arbitrary python code into the template. This limitation is preserved in other libraries like Askama, Tera, and minijinja. While those projects are all great, I personally found them lacking in usability.
This project while much younger than Askama and other template engines, is in a state that I believe to be very usable, in fact it is being used in production for multiple projects in my office.
If you have suggestions, features, questions, or anything else please feel free to open an issue. I could especially use extra help writing unit tests for stuff, and would be open to working with others to get that done.
Check out the book for in depth documentation.
Stilts uses a procedural derive macro on a struct to generate template rendering code which results in the template code being checked by the rust compiler for correctness.
Here is what some rust code defining a template looks like
use stilts::Template;
#[derive(Template)] // This derive macro will generate the template rendering code
#[stilts(path = "index.html")] // based on the contents of the given template path
struct IndexPage<'a> {
some_data: &'a str, // The fields on a struct are the variables
} // you want to use in your templateHere is what index.html could look like
<!DOCTYPE html>
<html>
<body>
<h1>My Index Page</h1>
{% some_data %} <!--This will print some_data to the template here using
the types implementaion of the Display trait-->
</body>
</html>In Stilts an expression is made up of two variants
single and block expressions. A single expression is
anything inside the delimiters {%%}. Whereas a block
expression has an opening single expression and a closing
single expression with some kind of content in-between. For example:
{% for i in 0..10 %}
This will be repeated 10 times
{% i %}
And I can put other expressions inside
{% end %}
Something you might notice if you have used Askama or Jinja before
is that normally to render the value of something you have to use
a different set of delimiters namely something like {{ some_data }}.
But here in Stilts there is only one set of delimiters {% some_data %}.
So how do we determine when the user wants to render something or just write some code? Well the answer is by determining if the rust code inside the delimiters is an expression or a statement. In rust an expression always produces a value and a statement doesn't.
Therefore if as a user we want to write some code but not render it to the template
all we have to do is add a semicolon. {% some_data; %} is a statement now not an
expression which means Stilts will insert that into the template rendering code as code
to run and not render it to the resulting template. This is familiar to many rust developers
as it is the same way we can omit the return keyword inside of functions by just ending it
with an expression.
What this also means is that you can put any arbitrary rust expression or statement inside of the
delimiters. For example {% let myval = some_data.split(' ').filter(|s| s != "abcd"); %}.
But you aren't limited to a single line either you can split them into as many lines as you want.
{% fn my_useful_func() {
// do some stuff
} %}
- The syntax is similar to Jinja but also more closely tied to rust
- Utilize rust's type system to verify your code
- Achieves performance comparable to Askama which is already very good
- Good error messages and formatting especially with optional fancy feature
- Works on stable rust
- Inheritance
- for loops
- if/ else if /else
- match expressions
- includes statements
- variables (as a result of allowing arbitrary rust expressions and statements)
- useful extension traits imported into scope
- Configurable Opt-out HTML escaping
- Create a templating language that is both familiar to jinja users and rust developers
- Have good error reporting and messages with useful error locations.
In the tooling directory there is a work-in-progress tree-sitter parser implementation. If you know better how to get that working that would be super cool.