README

Author: sakex

README.md

@@ -10,6 +10,8 @@ infrastructure for [mdbook](https://github.com/rust-lang/mdBook/):
 
 - [mdbook-i18n-helpers](./i18n-helpers/README.md): Gettext translation support
   for [mdbook](https://github.com/rust-lang/mdBook/)
+- [mdbook-tera-backend](./mdbook-tera-backend/README.md): Tera templates extension
+  for [mdbook](https://github.com/rust-lang/mdBook/)'s HTML renderer.
 
 ## Showcases
 
@@ -39,9 +41,13 @@ $ cargo install mdbook-i18n-helpers
 Please see [USAGE](./i18n-helpers/USAGE.md) for how to translate your
 [mdbook](https://github.com/rust-lang/mdBook/) project.
 
-## Changelog
+### `mdbook-tera-backend`
 
-Please see [CHANGELOG](CHANGELOG.md) for details on the changes in each release.
+Run
+
+```shell
+$ cargo install mdbook-tera-backend
+```
 
 ## Contact
 

mdbook-tera-backend/README.md

@@ -0,0 +1,84 @@
+# [Tera](https://github.com/Keats/tera) backend extension for `mdbook`'s HTML backend
+
+[![Visit crates.io](https://img.shields.io/crates/v/mdbook-i18n-helpers?style=flat-square)](https://crates.io/crates/mdbook-tera-backend)
+[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/mdbook-i18n-helpers/test.yml?style=flat-square)](https://github.com/google/mdbook-i18n-helpers/actions/workflows/test.yml?query=branch%3Amain)
+[![GitHub contributors](https://img.shields.io/github/contributors/google/mdbook-i18n-helpers?style=flat-square)](https://github.com/google/mdbook-i18n-helpers/graphs/contributors)
+[![GitHub stars](https://img.shields.io/github/stars/google/mdbook-i18n-helpers?style=flat-square)](https://github.com/google/mdbook-i18n-helpers/stargazers)
+
+This `mdbook` backend makes it possible to use [tera](https://github.com/Keats/tera)
+templates and expand the capabilities of your books. It works on top of the default HTML
+backend.
+
+## Installation
+
+Run
+
+```shell
+$ cargo install mdbook-tera-backend
+```
+
+## Usage
+
+### Configuring the backend
+
+To enable the backend, simply add `[output.tera-backend]` to your `book.toml`,
+and configure the place where youre templates will live.
+For instance `theme/templates`:
+
+```toml
+...
+
+[output.tera-backend]
+templates_dir = "theme/templates"
+
+...
+```
+
+### Creating templates
+
+Create your template files in the same directory as your book.
+
+```html
+<!-- ./theme/templates/language_list.html -->
+<ul>
+{% for identifier, language_name in get_context(key="output.i18n.languages") %}
+    <li>{{ identifier }}: {{ language_name }}</li>
+{% endfor %}
+</ul>
+```
+
+### Using templates in `index.hbs`
+
+Since the HTML renderer will first render Handlebars templates, we need to tell it to
+ignore tera templates using `{{{{raw}}}}` blocks:
+
+```html
+{{{{raw}}}}
+{% set current_language = ctx | get(key="config") | get(key="book") | get(key="language", default="en") %}
+<p>CURRENT LANGUAGE: {{ current_language }}</p>
+<p>All languages: {% include "language_list.html" %}</p>
+{{{{/raw}}}}
+```
+
+Includes names are based on the file name and not the whole file path.
+
+### Tera documentation
+
+Find out all you can do with Tera templates [here](https://keats.github.io/tera/docs/).
+
+## Changelog
+
+Please see [CHANGELOG](../CHANGELOG.md) for details on the changes in each
+release.
+
+## Contact
+
+For questions or comments, please contact
+[Martin Geisler](mailto:[email protected]) or 
+[Alexandre Senges](mailto:[email protected]) or start a
+[discussion](https://github.com/google/mdbook-i18n-helpers/discussions). We
+would love to hear from you.
+
+---
+
+This is not an officially supported Google product.