Allow for conditionals in templates

[mgeisler]

Problem

As far I can understand, the handlebars template system only allows for if-statements that evaluate a single variable. This limitation is on purpose to encourage people to put logic in the language serving the pages.

However, that also (implicitly) assumes that users have an easy way to change the backend. That is not the case for mdbook: changing the data available to the template requires modifying mdbook itself.

As a motivating example, I'm adding translations to Comprehensive Rust 🦀. For that, I would like to make the template react to the current language (exposed in language). I don't think it's possible for me to do something like

if language == "en" { ... } else { ... }

in my template right now? To handle this, I'm moving the logic to JavaScript or to wrapper scripts which drive the translation.

Similarly, I would like to expose a list of other languages to the template. It would use this to build a language picker. I believe doing that would require changing mdbook itself.

Proposed Solution

I would propose making it possible to use more powerful template languages. Something like Askama would enable much more rich templates. I could imagine that the template engine is passed the full book.toml file so that you can freely use new keys and values from it.

Notes

No response

[mgeisler]

Hehe, it turns out I was mistaken above. The Rust version of handlebars has "helpers" which allow me to write

{{#if (eq language "en")}}

in my template (see google/comprehensive-rust#394). It took me longer than I would like to admin to find that 😄 I don't seem to be able to find this info on the "original" documentation for the Handlebars language: https://handlebarsjs.com/guide/expressions.html.

[mgeisler]

I'll close this since I found the syntax for conditionals.