Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#9 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@aRustyDev ci sta già lavorando.

Dal 5/1/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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

Lingua principale
Rust
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aRustyDev/mdbook-htmx

Tutte le issue di aRustyDev/mdbook-htmx

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.