Merge pull request #56 from volfpeter/jinja-layouts

Jinja layouts

Author: volfpeter

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.jinja]
+indent_style = space
+indent_size = 2

.ignore

@@ -1 +1 @@
-!dev
+!dev/

AGENTS.md

@@ -2,15 +2,13 @@
 
 Unless explicitly requested:
 
-- **Do NOT** commit
+- **Do NOT** stage, commit, or push code
 - **Do NOT** write tests
 - **Do NOT** run code or applications
 
-**NEVER push code**
-
 **Never install anything**
 
-**ASK** questions if something is unclear or ambiguous
+**ASK** questions if something is unclear or ambiguous, make no assumptions
 
 Always aim for **simplicity**, **clarity**, be challenging to achieve this
 

README.md

@@ -17,6 +17,7 @@ Web development framework that brings the Next.js developer experience to Python
 - **Standard FastAPI** everywhere, so you can leverage the entire FastAPI ecosystem.
 - **JSX-like syntax** with async support for components, thanks to `htmy`.
 - First class **HTMX support** with `FastHX`.
+- Built-in **Jinja support** with zero configuration.
 - **Async** support everywhere, from APIs and dependencies all the way to UI components.
 - Support for both **JSON** and **HTML** (server side rendering) APIs.
 - **No JavaScript** dependencies
@@ -72,7 +73,7 @@ Consider supporting the development and maintenance of the project through [spon
 Similarly to Next.js, `holm` is built around the concept of [file-system based routing](https://volfpeter.github.io/holm/file-system-based-routing). This essentially means that your code structure is automatically mapped to a matching API:
 
 - You do not need to manually define routes, every [application component](https://volfpeter.github.io/holm/application-components) is automatically discovered and registered in the application.
-- You do not need to manually wrap pages in their layouts, it is automatically done based on your application's code structure.
+- You do not need to manually wrap pages in their layouts; this is automatically done based on your application's code structure.
 
 You can find all the necessary details on the [Application components](https://volfpeter.github.io/holm/application-components) page, and the [Quick start guide](https://volfpeter.github.io/holm/guides/quick-start-guide) can walk you through the process of creating your first application. The two are complementary documents, reading both is strongly recommended.
 
@@ -115,7 +116,9 @@ When building web applications, performance should be compared to an application
 
 ### Templating language support
 
-While certain features in `holm` rely heavily on the capabilities of `htmy` (for example its context and async support), you can still use other DSLs or templating languages (for example Jinja) in your application if you would like to. All you need to do is write a simple wrapper `htmy` component that internally offloads rendering to your framework of choice. You can find out more about this in the [htmy documentation](https://volfpeter.github.io/htmy/#compatibility-and-performance).
+`holm` ships with built-in **Jinja** support: `layout.jinja` files work out of the box as layouts, and `holm.JinjaTemplate` components render with zero configuration when `holm` owns the `htmy` renderer. See the [Jinja layout guide](https://volfpeter.github.io/holm/guides/jinja-layout) for details.
+
+Since `htmy` is the rendering engine, you can also use other DSLs or templating languages by writing a simple wrapper `htmy` component that offloads rendering to your framework of choice. You can find out more about this in the [htmy documentation](https://volfpeter.github.io/htmy/#compatibility-and-performance).
 
 ## Development
 
@@ -153,7 +156,7 @@ The most prominent frameworks in this category are Reflex and NiceGUI. They both
 
 This category includes frameworks like FastHTML or Ludic, and this is where `holm` belongs as well, but it has some key differentiators.
 
-First, `holm` brings the Next.js developer experience to Python with file-system based routing, automatic layout composition, and dynamic page metadata creation, and more. Thanks to `htmy`, it supports async code throughout the stack, even in components, and it also solves the prop drilling problem. While being built with `htmy`, it is easy to integrate with other templating libraries, like `Jinja` or `htpy`. And it provides all these features using standard, simple FastAPI patterns.
+First, `holm` brings the Next.js developer experience to Python with file-system based routing, automatic layout composition, and dynamic page metadata creation, and more. Thanks to `htmy`, it supports async code throughout the stack, even in components, and it also solves the prop drilling problem. While being built with `htmy`, it ships with built-in **`Jinja`** support and remains easy to integrate with other templating libraries, like `htpy`. And it provides all these features using standard, simple FastAPI patterns.
 
 ## License
 

docs/api/holm.md

@@ -27,3 +27,7 @@
         show_root_heading: true
         filters:
             - "!component"
+
+::: holm.JinjaTemplate
+    options:
+        show_root_heading: true

docs/api/utils.md

@@ -6,9 +6,9 @@ This section summarizes the different components of `holm` applications. If you
 
 *Layouts* are defined in the `layout.py` modules of packages as a callable `layout` variable (note that for example classes with an `__init__()` method, or `htmy.Component`s are callable, so they also qualify).
 
-As an alternative to Python-based layouts, you can also create `layout.html` files in packages, from which a Python layout equivalent is automatically generated.
+As an alternative to Python-based layouts, you can also create `layout.jinja` files in packages. These are standard Jinja2 templates, with the wrapped page (or any other child components) passed in as pre-rendered named slots. See the [Jinja layout guide](guides/jinja-layout.md) for a complete walkthrough.
 
-Note: If both `layout.py` and `layout.html` exist in the same package, the Python layout takes precedence. HTML layouts at the application root level require a Python package structure.
+Note: If both `layout.py` and `layout.jinja` exist in the same package, the Python layout takes precedence.
 
 Rules for *Python layouts*:
 
@@ -17,14 +17,15 @@ Rules for *Python layouts*:
 - `layout` can have additional arguments (position or keyword and keyword-only, but not positional-only). These arguments must be FastAPI dependencies. They will be automatically resolved during each request.
 - Returning a tuple or a list from a layout is **not allowed** unless the value is a `htmy.ComponentSequence`. Tuples and lists are always interpreted and treated as component sequences, so you don't need to track what kinds of components pages and layouts return. See `htmy.is_component_sequence()` for more information.
 
-Rules for *HTML layouts*:
+Rules for *Jinja layouts*:
 
-- Must follow Python `str.format()` syntax.
-- [Page metadata](#page-metadata) is accessible as `metadata`.
-- The current FastAPI request is accessible as `request`.
-- Use the `<!-- slot[name] -->` slot syntax for content injection (processed by `htmy.Snippet` and `htmy.Slots` components).
-- The default slot is `children` (`<!-- slot[children] -->`), which is filled with the return value of the wrapped layout or page.
-- The entire HTML layout processing pipeline can be customized using the `str_to_layout` argument of `App()`, allowing you to plug in tools like Jinja2 for example.
+- Must be valid Jinja2 templates.
+- [Page metadata](#page-metadata) is accessible as `metadata`, e.g. `{{ metadata.title }}`.
+- The current FastAPI request is accessible as `request`, e.g. `{{ request.url.path }}`.
+- Route parameters (resolved FastAPI dependencies) are accessible as `route_params`, e.g. `{{ route_params.current_user }}`.
+- Use the `{{ slots.name }}` syntax for content injection. The default slot is `children` (`{{ slots.children }}`), which is filled with the return value of the wrapped layout or page.
+- Return a mapping from a page or layout to provide content for multiple named slots.
+- App-wide default slots can be configured with the `layout_slots` argument of `App()`, e.g. `App(layout_slots={"navbar": navbar})`.
 
 By default, layouts automatically wrap all layouts and pages in subpackages. You can opt out of this behavior by wrapping the return value of a layout or page with the [`without_layout` utility](utilities.md#without_layout).
 

docs/application-components.md

@@ -12,7 +12,7 @@ Going through the [Application components](application-components.md) documentat
 - Underscores (`_`) are replaced with hyphens (`-`) in paths by default, unless a path segment corresponds to a path parameter, in which case the underscore is preserved.
 - Special files mark application components: `holm` looks for specific filenames within your application directory to discover application components and compose your application.
   - `page.py`: Creates a publicly accessible URL for a route segment.
-  - `layout.py`: Defines a shared UI that wraps a route segment and its children. `layout.html` is also supported as an HTML-based alternative (requires package structure at root level), see [Application components](application-components.md).
+  - `layout.py`: Defines a shared UI that wraps a route segment and its children. `layout.jinja` is also supported as a Jinja2-based alternative, see [Application components](application-components.md).
   - `actions.py`: Defines custom action endpoints for a route segment.
   - `api.py`: Creates custom API endpoints for a route segment.
 
@@ -93,7 +93,7 @@ Besides the special files (`page.py`, `layout.py`, `api.py`, etc.), you can plac
 
 In the example, `my_app/navbar.py` is not a special file, so it is not routable. It can define any components or utilities, like a `Navbar`, which can then be imported and used in the layouts, pages, or APIs of the application.
 
-`holm` also doesn't consider anything outside the application package as an application component. We could create a `my_components/` directory next to `my_app/` and have anything in it, including `page.py` files for example. The content of this package would be ignored by `holm`, it is not within the application package.
+`holm` also doesn't consider anything outside the application package as an application component. We could create a `my_components/` directory next to `my_app/` and have anything in it, including `page.py` files for example. The content of this package would be ignored by `holm`, as it is not within the application package.
 
 ### Submit handlers
 

docs/file-system-based-routing.md

@@ -1,38 +1,55 @@
-# HTML layout with default slots
+# Jinja layout default slots
 
-This guide builds on the [HTML layout guide](html-layout.md) and the [HTML multi-slot layout guide](html-multi-slot-layout.md) to demonstrate how to use **default slots** for shared components that appear on every page.
+This guide builds on the [Jinja layout guide](jinja-layout.md) and the [Jinja multi-slot layout guide](jinja-multi-slot-layout.md) to demonstrate how to use **default slots** for shared components that appear on every page.
 
 We will cover:
 
-- How to create a custom `str_to_layout` converter that provides default slots.
-- How to build a reusable navigation component that highlights the current page.
+- How to configure default slots with `App(layout_slots=...)`.
+- How to render default slots in a Jinja layout.
 
-The entire source code of this application can be found in the [examples/html-layout-default-slots](https://github.com/volfpeter/holm/tree/main/examples/html-layout-default-slots) directory of the repository.
+The entire source code of this application can be found in the [examples/jinja-layout-default-slots](https://github.com/volfpeter/holm/tree/main/examples/jinja-layout-default-slots) directory of the repository.
 
 Before you continue, make sure you have installed `holm` and either `uvicorn` or `fastapi-cli`!
 
 ## File structure
 
-The application uses a Python package structure (required for HTML layouts):
+The application uses a Python package structure:
 
 ```
-html-layout-default-slots/  # Root directory
-└── my_app/                 # Application package
-    ├── __init__.py         # Makes this a Python package (required for HTML layouts)
-    ├── main.py             # Application entry point with custom str_to_layout
-    ├── layout.html         # Root HTML layout with navbar and children slots
-    ├── navbar.py           # Shared navigation component
-    ├── page.py             # Home page
+jinja-layout-default-slots/  # Root directory
+└── my_app/                  # Application package
+    ├── __init__.py
+    ├── layout.jinja         # Root Jinja layout with navbar and children slots
+    ├── main.py              # Application entry point
+    ├── navbar.py            # Default navbar component
+    ├── page.py              # Home page
     └── about/
         ├── __init__.py
-        └── page.py         # About page
+        └── page.py          # About page
 ```
 
-## Create the navigation component
+## Create the application with a default slot
+
+Default slots are configured when you create the `holm` application:
+
+```python hl_lines="8"
+from holm import App
+
+from .navbar import navbar
+
+# `layout_slots` makes the `navbar` slot available to every component
+# in the application, including Jinja layouts, through
+# `htmy.jinja.DefaultSlots.from_context()`.
+app = App(layout_slots={"navbar": navbar})
+```
+
+`layout_slots` takes a mapping from slot name to `htmy` component. These slots are injected into the `htmy` rendering context using `htmy.jinja.DefaultSlots` and merged with any explicit slots returned by the wrapped page or layout. When there is a slot name conflict, the explicit slot provided by the wrapped page or layout takes precedence.
+
+## Create the default navbar component
 
 First we create `my_app/navbar.py` with a navigation component that highlights the current page:
 
-```python hl_lines="1 10 28-29 33-38"
+```python hl_lines="1 18 28"
 from fasthx.htmy import CurrentRequest
 from htmy import ComponentType, Context, component, html
 
@@ -73,48 +90,20 @@ def navbar(context: Context) -> ComponentType:
     )
 ```
 
-These are the most important details you should notice:
+The most important details:
 
 - `CurrentRequest.from_context()` is used to get the current FastAPI request from the `htmy` rendering context.
 - The `nav_item` helper applies highlighting when the link matches the current path.
 
-## Create the custom layout converter
-
-Create `my_app/main.py` with a custom `str_to_layout` converter that provides the navbar as a default slot:
+## Create the Jinja layout with slots
 
-```python hl_lines="2-3 5 8-14 18"
-from holm import App
-from holm.typing import Layout
-from holm.utils import snippet_to_layout
+Create `my_app/layout.jinja` with slots for both the navbar and page content:
 
-from .navbar import navbar
-
-
-def str_to_layout_with_navbar(content: str) -> Layout:
-    """
-    Custom string to `Layout` converter function for the application.
-
-    It makes a `navbar` component available to every HTML layout in the `navbar` slot.
-    """
-    return snippet_to_layout(content, default_slot_mapping={"navbar": navbar})
-
-
-app = App(str_to_layout=str_to_layout_with_navbar)
-```
-
-The important bit here is the `str_to_layout_with_navbar()` function (which wraps `snippet_to_layout`), and how we pass it to `App()`.
-
-The `default_slot_mapping` argument specifies components that will be automatically provided for slots unless the page explicitly overrides them. In this case it means HTML layouts will always have access to our `navbar` without pages having to return it themselves.
-
-## Create the HTML layout with slots
-
-Create `my_app/layout.html` with slots for both the navbar and page content:
-
-```html hl_lines="14-15 18-19"
+```jinja hl_lines="4 14-15 18-19"
 <!doctype html>
 <html>
   <head>
-    <title>{metadata[title]}</title>
+    <title>{{ metadata.title }}</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <link
@@ -124,12 +113,12 @@ Create `my_app/layout.html` with slots for both the navbar and page content:
   </head>
   <body class="container-fluid">
     <header class="container">
-      <!-- The navbar component added by the layout converter goes to the navbar slot: -->
-      <!-- slot[navbar] -->
+      <!-- The navbar component provided by `layout_slots` -->
+      {{ slots.navbar }}
     </header>
     <main class="container">
-      <!-- Page content goes here, to the usual children slot: -->
-      <!-- slot[children] -->
+      <!-- Page content goes here, to the usual children slot -->
+      {{ slots.children }}
     </main>
     <footer class="container">
       <p>© 2026 My App</p>
@@ -138,16 +127,16 @@ Create `my_app/layout.html` with slots for both the navbar and page content:
 </html>
 ```
 
-Our layout has two slots:
+The layout has two slots:
 
-- `<!-- slot[navbar] -->` receives the navbar component from the default slot mapping.
-- `<!-- slot[children] -->` receives the page's main content.
+- `{{ slots.navbar }}` receives the navbar component from `layout_slots`.
+- `{{ slots.children }}` receives the page's main content.
 
 ## Create your home page
 
-We can now create our home page in `my_app/page.py`, which is essentially the same as in the HTML layout guide:
+We can now create our home page in `my_app/page.py`, which is essentially the same as in the Jinja layout guide:
 
-```python hl_lines="16"
+```python
 from htmy import Component, html
 
 metadata = {"title": "Home | My App"}
@@ -181,7 +170,7 @@ async def metadata(featured: bool = False) -> dict[str, str]:
     """
     Dynamic metadata based on query parameters.
 
-    This function could be both sync or async. It's just a standard FastAPI dependency.
+    This function could be either sync or async. It's just a standard FastAPI dependency.
     """
     title = "Featured About" if featured else "About"
     return {"title": f"{title} | My App"}
@@ -227,3 +216,10 @@ You can now open the application in the browser:
 - `http://localhost:8000/about?featured=true`: Featured about page variant
 
 You'll see the navigation bar on every page with the current page highlighted.
+
+## Next steps
+
+Now that you understand default slots:
+
+- Review the [Jinja layout guide](jinja-layout.md) for the basics of Jinja layouts, custom `htmy` setups, and nested layouts.
+- Learn how to use multiple layout slots for more complex page structures in the [Jinja multi-slot layout guide](jinja-multi-slot-layout.md).