Templates & Static Files

axion renders server-side pages with Jinja2 and serves static assets (CSS, JS, images) from configured directories.

Templates

Templates are resolved from TEMPLATE_DIRS (default: <BASE_DIR>/templates, which is the package root for library use — override it in your project’s config/settings.py). Directories are searched in order and the first match wins.

# config/settings.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
TEMPLATE_DIRS = [BASE_DIR / "views"]

Render a template from a route:

@app.route("/")
def index(response: Response):
    response.render("index.html", title="Home", user="Alice")

response.render(template, **context) renders the template with the given context and sends it as text/html. Autoescaping is on by default, so user data is escaped automatically. If no template is found a 404 with the body Template Not Found is returned.

Pass a list to pick the first existing template, or a pre-built jinja2.Template:

response.render(["mobile.html", "index.html"], title="Home")

Example template

<!DOCTYPE html>
<html>
<head>
    <title></title>
    <link rel="stylesheet" href="/static/css/styles.css">
</head>
<body>
    <h1></h1>
    <p>Hello, !</p>
</body>
</html>

Static files

Static assets live in STATIC_DIRS (default: <BASE_DIR>/static, relative paths are resolved against the package BASE_DIR). They are served at STATIC_URL (default /static/).

# config/settings.py
STATIC_DIRS = [BASE_DIR / "static"]

A request to /static/css/styles.css serves static/css/styles.css with a content type guessed from the extension. Path traversal is blocked: files must resolve inside one of the configured directories.

Media and public files

Two more directories are served for files that aren’t static assets:

Static files are checked after routing, so a route always wins over a file with the same path. Paths under STATIC_URL and MEDIA_URL are served from their own directories only; every other unmatched path falls through to PUBLIC_DIR.

Next steps