# Getting started
Every web framework eventually asks the same question: how do you turn data into HTML? Robyn's answer out of the box is Jinja2. This package offers a second answer, the one people who built on Pyramid or Zope tend to miss the moment they leave: [Chameleon](https://chameleon.readthedocs.io/) page templates.
A Chameleon template is an ordinary HTML file. Open one in a browser before it has ever been rendered and you still see a page, placeholders and all, because the logic lives inside attributes the browser ignores. `tal:repeat` loops, `tal:condition` hides, and `${...}` fills in values with real Python expressions. There is no second language layered over your markup. Your designer can open the file. Your editor can validate it. And chameleon-robyn wires those templates into Robyn with a single decorator: your handler returns a `dict`, and a rendered `Response` comes out the other side.
One honest note before we begin: the project is in alpha. The API is small and unlikely to change much, but there are no stability promises yet.
# Install
``` bash
uv pip install chameleon-robyn
```
Or with pip:
``` bash
pip install chameleon-robyn
```
This brings in `robyn` and `chameleon` as dependencies. Python 3.10 or newer is required.
# The site we are building
This guide follows one project from the first page to the last error message: the website for a small podcast. It has an episode list, a page per episode, a guest directory, a search box, an XML feed for the robots, and the occasional visitor who types a URL that does not exist. Every snippet in the guide comes from that site, and the repository's `example/` folder holds the finished version.
# Project layout
Nothing about the layout is enforced, but this is the shape that makes the rest of the guide read naturally:
``` text
my_app/
├── app.py
└── templates/
└── home/
└── index.pt
```
Every template path you hand the library is relative to the `templates/` folder you register at startup. The folder name is yours to choose.
# Your first page
Start with `templates/home/index.pt`. Notice that it is just HTML with two extra ideas: `${name}` to drop in a value, and `tal:repeat` on the element that should repeat.
``` xml
Hello, ${name}!
```
Now `app.py`. Three lines matter: the import, the [global_init()](../reference/global_init.md#chameleon_robyn.global_init) call that says where templates live, and the decorator above the handler.
``` python
from pathlib import Path
from robyn import Robyn
import chameleon_robyn
app = Robyn(__file__)
# Point Chameleon at your templates folder (do this once at startup)
template_folder = (Path(__file__).resolve().parent / 'templates').as_posix()
chameleon_robyn.global_init(template_folder, auto_reload=True)
@app.get('/')
@chameleon_robyn.template('home/index.pt')
async def index(request):
return {'name': 'World', 'items': ['Robyn', 'Chameleon', 'Python']}
app.start(host='127.0.0.1', port=8000)
```
Run `python app.py` and open . A heading and a three-item list greet you. That handler never touched a string of HTML, and it never will.
# What just happened
- [global_init()](../reference/global_init.md#chameleon_robyn.global_init) told Chameleon where the templates live. It runs once at startup, and its settings are the subject of [Configuration](configuration.md).
- `@template('home/index.pt')` wrapped the handler. The handler returned a `dict`, and every key in it became a variable the template could see.
- The decorator rendered the template and handed back a Robyn `Response` with status 200 and a `Content-Type` of `text/html; charset=utf-8`.
- Robyn's route decorator stayed on the outside. `@template` sits directly above the function, and it is equally happy with `def` and `async def`.
That is the whole mental model. Everything else in this guide is a refinement of it.
# Run the finished examples
Two runnable apps live in the repository. The first shows every feature on the podcast site: episodes and guests, a shared METAL layout, search by query string, the XML feed, a redirect, a cookie set from a rendered page, and a friendly 404. The second is the same app with the episode card pulled out into a reusable partial.
``` bash
git clone https://github.com/mikeckennedy/chameleon-robyn.git
cd chameleon-robyn
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e ".[examples]"
python example/app.py # core features
python example-partials/app.py # the same app using chameleon-partials
# Open http://127.0.0.1:5555
```
# Where to go next
- [The @template decorator](template-decorator.md): the return-value contract, templates that name themselves, async handlers, status codes, redirects, and setting a cookie on a rendered page.
- [Writing templates](templates.md): a TAL cheat sheet, shared layouts with METAL, escaping, Alpine.js and htmx attributes, and chameleon-partials.
- [Friendly 404 pages](not-found.md): one call to [not_found()](../reference/not_found.md#chameleon_robyn.not_found) and the stack trace never reaches the visitor.
- [Rendering outside handlers](lower-level-api.md): [render()](../reference/render.md#chameleon_robyn.render), [response()](../reference/response.md#chameleon_robyn.response), and the standalone [ChameleonTemplate](../reference/ChameleonTemplate.md#chameleon_robyn.ChameleonTemplate) class.
- [Configuration](configuration.md): every [global_init()](../reference/global_init.md#chameleon_robyn.global_init) setting, and the one that bites people in tests.
- [Testing your handlers](testing.md): no server, no client, just function calls.
- [Errors and how to fix them](troubleshooting.md): a field guide to every exception you can meet.
- [How it works](how-it-works.md): a tour of the three source files.
- [FAQ](faq.md)
- [API reference](../reference/index.md)