Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

docs(adr): ADR-0001: Use Tera as Default Template Engine

Abierto
  • ¿Algo no está bien?
#9 0 comentarios 0 reacciones 1 asignado Ver en GitHub

@aRustyDev ya está trabajando en esto.

Desde el 5/1/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

documentation

ADR-0001: Use Tera as Default Template Engine

Status

Accepted

Context

The mdbook-htmx backend needs a template engine to render HTMX-enhanced HTML pages. The skeleton files indicated support for multiple engines:

  • Nunjucks (JavaScript)
  • Handlebars (Rust/JS)
  • Liquid (Ruby/Rust)
  • Tera (Rust-native)

The backend is written in Rust to align with MDBook's ecosystem and ensure seamless integration via the mdbook-renderer crate.

Decision Drivers

  1. Language Consistency - Backend is Rust; prefer Rust-native engines
  2. Performance - Compile-time template validation, no FFI overhead
  3. Feature Parity - Must support: includes, extends, filters, conditionals
  4. Ecosystem Fit - Used by other Rust documentation tools (Zola)
  5. Maintenance - Active development, good documentation

Options Considered

Option A: Tera

Pros:

  • Pure Rust, compiles with the backend
  • Jinja2-compatible syntax (familiar to Python/Django developers)
  • Template inheritance ({% extends %}, {% block %})
  • Custom filters and functions
  • Used by Zola (similar documentation use case)
  • Compile-time syntax validation

Cons:

  • Less feature-rich than full Jinja2
  • Smaller community than Handlebars
Option B: Handlebars (handlebars-rs)

Pros:

  • Rust implementation available
  • Wide adoption across languages
  • Logic-less philosophy (simpler templates)

Cons:

  • No template inheritance (only partials)
  • Verbose for complex layouts
  • Logic-less can be limiting for HTMX patterns
Option C: Liquid (liquid-rust)

Pros:

  • Rust implementation available
  • Simple syntax
  • Used by Jekyll

Cons:

  • Limited control flow
  • No template inheritance
  • Less expressive for component-based layouts
Option D: Nunjucks (via wasm or subprocess)

Pros:

  • Full Jinja2 compatibility
  • Rich feature set

Cons:

  • JavaScript runtime dependency
  • Performance overhead (subprocess or WASM)
  • Complicates build/distribution

Decision

Use Tera as the default template engine.

Rationale:

  1. Pure Rust eliminates external dependencies
  2. Template inheritance is essential for layout.html → page.html pattern
  3. Jinja2 syntax is widely known
  4. Zola uses Tera for similar documentation purposes, proving suitability
  5. Custom filters enable {{ asset('path') }} helper for hashed filenames

Consequences

Positive
  • Single-binary distribution (no runtime dependencies)
  • Fast template compilation and rendering
  • Familiar syntax for most developers
  • Strong typing integration with Rust structs
Negative
  • Users familiar with Handlebars/Liquid need to learn Tera
  • Some advanced Jinja2 features not available
Mitigation
  • Document Tera syntax in SPEC
  • Provide example templates
  • Consider optional Handlebars support in future (via feature flag)

References

Lenguaje dominante
Rust
Estrellas
0
Forks
1
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de aRustyDev/mdbook-htmx

Todos los issues de aRustyDev/mdbook-htmx

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.