Create a template

Create a template#

This tutorial walks you through building a minimal Cookieplone template repository. By the end, you will have a working template that you can run locally with cookieplone.

Prerequisites:

  • uv installed.

  • Basic familiarity with Jinja2 templating syntax.

  • Git installed.

Step 1: Create the repository structure#

A Cookieplone template repository requires at minimum a root cookiecutter.json and at least one template directory. Create the following structure:

mkdir my-template
cd my-template
git init

Then create these files:

my-template/
├── cookiecutter.json          ← root manifest (lists templates)
└── templates/
    └── myproject/             ← one template
        ├── cookieplone.json   ← schema for this template
        └── {{cookiecutter.project_slug}}/
            ├── README.md
            └── pyproject.toml

Step 2: Write the root manifest#

The root cookiecutter.json tells Cookieplone which templates this repository provides. Create cookiecutter.json:

{
  "templates": {
    "myproject": {
      "path": "./templates/myproject",
      "title": "My project template",
      "description": "A minimal example project."
    }
  }
}

Step 3: Write the template schema#

The cookieplone.json file inside each template defines the questions asked during generation. Create templates/myproject/cookieplone.json:

{
  "title": "My project template",
  "description": "A minimal example project.",
  "version": "2.0",
  "properties": {
    "project_title": {
      "type": "string",
      "title": "Project title",
      "description": "The human-readable name of your project.",
      "default": "My Project"
    },
    "project_slug": {
      "type": "string",
      "title": "Project slug",
      "description": "Identifier used for the directory name.",
      "default": "my-project"
    },
    "author_name": {
      "type": "string",
      "title": "Author name",
      "default": "Jane Developer"
    },
    "author_email": {
      "type": "string",
      "title": "Author email",
      "default": "jane@example.com"
    }
  }
}

Step 4: Write the template files#

Create the Jinja2-templated files that Cookieplone will render. The directory name {{cookiecutter.project_slug}} becomes the generated folder name.

Create templates/myproject/{{cookiecutter.project_slug}}/README.md:

# {{cookiecutter.project_title}}

Created by {{cookiecutter.author_name}} <{{cookiecutter.author_email}}>.

Create templates/myproject/{{cookiecutter.project_slug}}/pyproject.toml:

[project]
name = "{{cookiecutter.project_slug}}"
authors = [
    {name = "{{cookiecutter.author_name}}", email = "{{cookiecutter.author_email}}"},
]

Step 5: Run your template locally#

Test your template by pointing Cookieplone at the local directory:

uvx cookieplone /path/to/my-template

Cookieplone reads the root cookiecutter.json, presents your template in the menu, asks the questions from cookieplone.json, and generates output in the current directory.

Step 6: Inspect the output#

After answering the prompts, a new directory appears with your rendered files. Open README.md to confirm the values were substituted correctly.

What's next?#

Contents