Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

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

未关闭
  • 哪里不对？
#9 0 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

@aRustyDev 已经在做这个了。

开始于 2026年1月5日。

评估

这个 Issue 还没有评估数据。

描述

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

主要语言
Rust
星标
0
派生
1
30 天内没有已合并 PR

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

aRustyDev/mdbook-htmx 的其他 Issue

查看 aRustyDev/mdbook-htmx 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。