texsite

texsite delivers great and ready-to-use page templates for the modern, flexible and user-focused web content management system Wagtail CMS backed by the popular Django web framework, both written in Python.

Based on the amazing StreamField introduced with Wagtail release 1.0, which texsite uses extensively, it has never been easier for editors to author awesome pages. Read more on how this concept works in the great blog article Rich text fields and faster horses written by Matt Westcott, lead technical developer of Wagtail.

Project scope

texsite is developed primarily as our own deployable Wagtail application, serving multiple themed sites from a single instance. It is published to PyPI for provenance and reuse, and its themes and blocks are free to draw on. Standalone third-party integration into another Wagtail project is provided as-is and is not a primary supported path.

Features

• Themes:
  • Clean Blog
  • Business Casual
  • Freelancer
  • Xperience
  • Serene
  • Agency
• Outstanding test coverage
• Continuously integrated codebase

Technical requirements

New feature releases frequently add support for newer versions of underlying technologies and drop support for older ones. The compatible versions of Wagtail, Django and Python for each texsite release are:

texsite only supports SQLite databases.

Code and contribution

The code is open source and released under the ISC License (ISCL). It is available on Gitlab and follows the guidelines about Semantic Versioning for transparency within the release cycle and backward compatibility whenever possible.

All contributions are welcome, whether bug reports, code contributions and reviews, documentation or feature requests.

If you're a developer, fork the repo and prepare a merge request:

# Prepare your environment
uv sync
git config core.hooksPath .githooks

# Running tests
uv run python -m django test --settings=tests.settings

# Code quality
uv run ruff format texsite tests
uv run ruff check texsite tests

# Translations
uv run python -m django makemessages --all
uv run python -m django compilemessages

Data migrations that transform body JSON via raw SQL must unwrap block items: Wagtail serializes every StreamField block and ListBlock item as a {"type": ..., "value": ..., "id": ...} wrapper, so read item['value'] to reach the actual field value. See texsite/core/migrations/0008_migrate_pages_to_universal.py and 0015_convert_xperience_hero_images.py for the pattern.

Installation

Install texsite directly from PyPI using pip:

pip install texsite

Configuration

All configuration details can be found in texsite/settings/config.py. The available environment variables and their defaults are defined there.

We recommend using a .env file to set the environment variables. manage.py loads it automatically, and it is also recognised by Docker compose.

If you need more flexibility, you may provide your own settings module. This is done by setting the DJANGO_SETTINGS_MODULE environment variable to the path of your custom settings module.

Local development

Run the development server locally without Docker:

cp .env.example .env
mkdir -p .data
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver 127.0.0.1:8000

See the Configuration section above for available environment variables.

Docker

We provide a Dockerfile to build a production-ready image. Production routing lives outside this repository; compose.yml covers local development and pre-release testing — see it for services, ports and mounts.

docker compose run --rm cli migrate            # management commands run through `cli`
docker compose up                              # hot-reloading dev server
docker compose --profile release up --build    # prod-like image test

Verifying rendering changes

For template and markup changes, compare screenshots of the live production sites (the known-good baseline) with the local dev server running on a copy of production data. Not every theme has production content for every block type; blocks without a production baseline can only be checked on dev.

For styling changes, the screenshots service shoots a site from the dev server before and after the change and pairs the results side by side. The dev server must accept the site's hostname, for example with TEXSITE_ALLOWED_HOSTS=* in .env.

docker compose run --rm screenshots shoot before www.example.com /,/about/ --selector '.my-class'
# make the change
docker compose run --rm screenshots shoot after www.example.com /,/about/ --selector '.my-class'
docker compose run --rm screenshots compare before after   # .screenshots/compare-*.png

Multi-Tenant Hosting

texsite supports multi-tenant hosting where a single instance serves multiple customer domains. Each tenant gets their own:

• Wagtail Site with custom root page
• Collection for media isolation
• User group with scoped permissions
• Site branding (logo/favicon) via Wagtail admin

New Tenant Setup (Wagtail Admin)

1. Create root page under the Root page
2. Create Wagtail Site pointing to the new root page with correct hostname/port
3. Create Collection for tenant media (Images/Documents)
4. Create Group with permissions:
   • add_page, change_page, publish_page on root page
   • add_image, change_image, choose_image on collection
   • add_document, change_document, choose_document on collection
5. Create users and assign to the tenant group
6. Configure SiteBranding (Settings > Site branding)