Clay

An amazing prototyping tool.

With Clay you can forget about making changes to dozens of HTML files just because you need to add a link in the footer.

You can also use it to prototype your AJAX-driven application or the responses of sending forms, because it acts like a real server.

Install

uv tool install clay

Quickstart

clay new mysite

will generate a new app container with the following structure:

mysite
  ├── static/
  ├── clay.yaml
  ├── index.html
  └── ...other files

You can also use an optional project template path or git URL. For the URLs, "gh:" works as a shortcut of "https://github.com/" and "gl:" as a shortcut of "https://gitlab.com/". For example:

# Absolute or relative path.
clay new myapp /path/to/project/template

# GitHub repo. Note the ".git" postfix.
clay new myapp https://github.com/lucuma/clay-template.git

# The same GitHub repo with shortcut
clay new myapp gh:/lucuma/clay-template.git

Development server

Inside that folder, run the development server with:

clay run

and your site'll be available at http://0.0.0.0:8080/.

Anything inside the static folder is served as-is under the /static/ path. For example you can see myapp/static/image.png at the http://0.0.0.0:8080/static/image.png URL.

Any file outside the static folder, is rendered as a page.

For example, myapp/page.html is rendered and shown at http://0.0.0.0:8080/page.html, as an HTML page.

And myapp/foo/bar.json is rendered and shown at http://0.0.0.0:8080/foo/bar.json as a JSON document.

Remember to put inside static anything you don't want to be rendered.

Build version

To generate a static version of your site, first, stop the server with Control + C, and then run:

clay build

and all the templates will be processed and the result stored inside the build folder.

Static files

If you have folders in your project, you might be tempted to write internal URLs like this

<!-- DON'T DO THIS ->
href="../a.html"
src="../static/main.js"

Don't do it. Is error-prone and could not work as expected if you do it in a base layout, for example. Always write the internal URLs using their path from the root of the project, like this:

href="/a.html"
src="/static/main.js"

That'll work on the development server and also when generating a static version of your site, Clay will convert them into relative paths automatically.

Template globals

When writing your templates, in addition of what is normally available in Jinja templates you have access to some other helper functions:

The python's functions dir, enumerate, map, zip, and len.
The now function, as an alias to datetime.datetime.utcnow.
The active function, to set an "active" class in navigations/menus when the current page match.

`active()`

active(*url_patterns, partial=False, class_name="active")

TODO

The `clay.yaml` file

If a YAML file named clay.yaml is found in the root of the project, it will be read and used for configuring Clay.

---
# Shell-style patterns files/folders that must not be copied.
# Use quotes.
exclude:
  - ".*"
  - ".*/*"
  - "~*"
  - "~*/*"
  - "_*"
  - "_*/*"
  - "*.txt"

# Shell-style patterns files/folders that *must be* copied, even if
# they are in the exclude list.
# Use quotes.
include:
  - "robots.txt"
  - "humans.txt"

# Jinja extensions to use
jinja_extensions:

# Shell-style patterns of files outside `static/` that must be copied
# as-is instead of trying to interpret them as Jinja templates.
# Use quotes.
binaries:
  - "favicon.ico"

Happy coding!

Development

Create the project environment and install all development dependencies:

uv sync

Run the test and lint suites through the locked project environment:

uv run pytest -x clay tests
uv run flake8 --config=setup.cfg clay tests

Metadata

Release files for clay 4.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for clay 4.7.1
File	Size	Uploaded
clay-4.7.1.tar.gz	25.8 kB	Jul 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for clay 4.7.1
File	Interpreter	ABI	Platform	Reset
clay-4.7.1-py3-none-any.whl 26.0 kB Jul 14, 2026	Python 3	none	any	Details

Total release size: 51.8 kB

Release files / clay-4.7.1.tar.gz

Download URL	clay-4.7.1.tar.gz
Size	25.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`bad125f9ddba9a46549c93d7a60535e8e9b04620e89ea1c790716afb26fdf7ab`
BLAKE2b-256 checksum How to use checksums	`45c5d448078ded9e7f93e74fdaa6ae4a696a25b0ddeb168e2448ff97060c6bee`
Upload date	Jul 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / clay-4.7.1-py3-none-any.whl

Download URL	clay-4.7.1-py3-none-any.whl
Size	26.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`368712d357f7334fbf56057ee26dc6937cef941eb0a01859fb7b8bbd90c99ae4`
BLAKE2b-256 checksum How to use checksums	`c4ad6387c58a2b7fbd051d9d545f0cdee0ebd2d8030676afa41a475530b6f54b`
Upload date	Jul 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`