Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Gemini Ask Copilot
3 min read 510 words Updated 25 days ago

Kida 0.2.6

Regions, render_block def scope, top-level defs in blocks, framework integration docs

Status: Released March 9, 2026.

Regions are the headline feature in 0.2.6. They are parameterized blocks that work as both blocks (forrender_block()) and callables (for {{ name(args) }}). Use them when you need parameterized fragments for HTMX partials, OOB updates, or layout composition.

Highlights

  • {% region %} blocks — Parameterized blocks that work as both blocks (for render_block()) and callables (for {{ name(args) }}). Support required and optional params, default values, and access to outer render context.
  • Region metadata —BlockMetadata now includes is_region and region_params. TemplateMetadata.regions()returns only region-typed blocks for framework OOB discovery (e.g. Chirp's AST-driven layout contracts).
  • render_block def scope fix — Blocks can now call defs from the same template when defs are top-level; previouslyrender_block("content") would fail with NameError if the block used {{ helper() }} and helperwas a def in the same file.
  • Docs — Functions reference, render_block scope troubleshooting, framework integration guide with Chirp + Regions step-by-step.

Added

Regions

  • {% region %} blocks — Parameterized blocks that work as both blocks (for render_block()) and callables (for {{ name(args) }}). Use when you need parameterized fragments for HTMX partials, OOB updates, or layout composition.
  • Region metadata —BlockMetadata now includes is_region and region_params. TemplateMetadata.regions()returns only region-typed blocks for framework OOB discovery.

Documentation

  • Functions reference — New syntax page documenting{% def %}, {% region %}, parameters, typed params, slots, caller(), has_slot(), and the regions vs defs comparison.
  • render_block and def scope troubleshooting — New guide explaining the historical limitation where blocks could not inherit defs from the same template, how 0.2.6 lets blocks call top-level defs, and when to still split defs into imports or use regions for shared logic.
  • Framework integration docs — Expanded guide with Chirp + Regions step-by-step, adapter pattern, and case studies for Bengal, Chirp, and Dori.
  • Doc tracks — Learning tracks for Chirp+Kida, framework integration, and Jinja2 migration.
  • Render block tests — Test suite forrender_block()contract (Chirp fragment dependency), inheritance, regions, and slot context inheritance.

Changed

  • Top-level defs and regions in globals setup — Defs and regions at template top-level are now compiled into_globals_setup, so render_block() has access to macros and region callables. Fixes NameErrorwhen blocks call defs defined in the same template.
  • Compiler preamble refactor —_make_runtime_preamble() centralizes shared runtime locals (scope stack, escape/str, buf/append, acc). _make_block_preamble() and _make_render_preamble()delegate to it.
  • Block/region name collision — Compiler rejects duplicate block and region names withTemplateSyntaxError.

Fixed

  • render_block def scope — Blocks can now call defs from the same template when defs are top-level; previouslyrender_block("content") would fail with NameError if the block used {{ helper() }} and helperwas a def in the same file.

Upgrade Notes

  1. No breaking changes — Existing templates continue to work.
  2. Block/region name collision — Compiler now rejects duplicate block and region names withTemplateSyntaxError. If you had overlapping names, rename one.