Creating Custom Templates¶

Learn how to create distributable templates from your RhamaaCMS projects.

What is a Template?¶

A RhamaaCMS template is a ZIP file containing:

Django/Wagtail project structure
{{ project_name }} placeholders (replaced by wagtail start)
Static assets
Requirements and config

Why Create Templates?¶

Share project setups with your team
Distribute custom configurations
Create starting points for client projects

Using `build-template`¶

The easiest way to create a template:

# From your project directory
rhamaa cms build-template

# Template created: dist/rhamaacms-template.zip

What Gets Converted¶

Placeholders Replaced¶

Original	Becomes
`myproject`	`{{ project_name }}`
`my-project`	`{{ project_name }}`
`MyProject`	`{{ project_name }}`
`MYPROJECT`	`{{ project_name\\|upper }}`

Package Renamed¶

Your project folder becomes project_name:

myproject/          → project_name/
├── settings/
├── urls.py
└── wsgi.py

Templates Wrapped¶

HTML templates get wrapped with {% verbatim %}:

{% verbatim %}
<!DOCTYPE html>
<html>
<head>{{ seo_metadata }}</head>
</html>
{% endverbatim %}

This prevents Django from rendering template tags during wagtail start.

Options¶

Specify Slug¶

rhamaa cms build-template --slug myproject

Custom Output¶

rhamaa cms build-template --output my-template.zip

Skip Verbatim¶

rhamaa cms build-template --no-wrap-templates

Warning: Only skip if your templates don't use Django template syntax.

Ignored Files¶

These are automatically excluded:

.git/
.venv/
venv/
node_modules/
__pycache__/
*.pyc
static_compiled/
dist/
.vscode/
.idea/

Using Your Template¶

Local File¶

wagtail start myproject --template=/path/to/template.zip

URL¶

wagtail start myproject --template=https://example.com/template.zip

With RhamaaCLI¶

Add to project_template_list.json:

{
  "custom": {
    "name": "My Custom Template",
    "description": "Description here",
    "repository": "https://github.com/user/repo",
    "branch": "main"
  }
}

Then:

rhamaa cms start myproject --template custom

Best Practices¶

Clean before building — Remove test data and media
Update fixtures — Include demo data if helpful
Document customizations — Add README to template
Version your templates — Use git tags
Test thoroughly — Create a project from template and verify

Manual Template Creation¶

For full control, you can manually create templates:

1. Prepare Project¶

Replace your project name with {{ project_name }} in all files.

2. Rename Directory¶

mv myproject project_name

3. Wrap Templates¶

Add {% verbatim %} around HTML templates.

4. Create ZIP¶

zip -r template.zip project_name/ -x "*.pyc" -x "__pycache__/*" -x ".git/*"

Next Steps¶

CLI Commands Reference