This project is a collection of templates for Plone integrators to use through Cookieplone.
Set up your system with Plone's Prerequisites for installation.
Select a template with the following command:
uvx cookieplone╭───────────────────────────────────────────────────────────── cookieplone ──────────────────────────────────────────────────────────────╮
│ │
│ ******* │
│ *************** │
│ *** *** ********* *** *** │
│ *** *** *** *********** *** * R * │
│ *** ***** *** *** *** *** *** │
│ *** *** *** *** *** *** **** *** *** **** │
│ *** *** *** *** *** *** ******** ********* ******** │
│ *** ***** *** *********** *** *** *** **** *** *** *** │
│ *** *** *** *** ********* *** *** *** *** *** ********** │
│ *** ***** *** *** *** *** *** *** *** ********* │
│ *** *** *** *** **** *** *** *** *** *** ... │
│ *** *** *** ***** ******** *** *** ******** │
│ *************** *** *** **** *** *** **** │
│ ******* │
│ │
│ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Templates │ │
│ │ ┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │ │
│ │ ┃ # ┃ Title ┃ Description ┃ │ │
│ │ ┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ │
│ │ │ 1 │ Volto Project │ Create a new Plone project that uses the Volto frontend │ │ │
│ │ │ 2 │ Classic UI Project │ Create a new Plone project that uses Classic UI │ │ │
│ │ │ 3 │ Backend Add-on for Plone │ Create a new Python package to be used with Plone │ │ │
│ │ │ 4 │ Frontend Add-on for Plone │ Create a new Node package to be used with Volto │ │ │
│ │ │ 5 │ Add-on for Plone (Backend + Volto) │ Create a new codebase for a Plone add-on that includes both backend and Volto │ │ │
│ │ │ │ │ frontend │ │ │
│ │ │ 6 │ Seven Frontend Add-on for Plone │ Create a new Node package to be used with Seven │ │ │
│ │ │ 7 │ Documentation scaffold for Plone projects │ Create a new documentation scaffold for Plone projects │ │ │
│ │ └───┴───────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────┘ │ │
│ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Select a template [1/2/3/4/5/6/7] (1):
To publish your project to your Git service provider, first create an empty remote repository with your Git service provider. Then navigate to the root of your generated project folder. Finally, issue the following commands.
Note
If your remote repository is private, you'll need to manage authorization when you push commits upstream.
git status
git commit -m "first commit"
git remote add origin https://<git_service_provider>/<organization_or_username>/<project_slug>.git
git branch -M main
git pushYour remote repository should now be populated with your generated project.
The Cookieplone template documentation_starter supports publishing documentation and pull request preview builds on Read the Docs.
First, create an account on Read the Docs, then follow their documentation to add a documentation project and configure pull request previews.
Next, update your documentation files.
Search for the string MY_READTHEDOCS_PROJECT_SLUG throughout your project, and replace it your project's slug that Read the Docs assigned to your project.
Finally, commit and push your changes to your remote repository.
Read the Docs will build documentation and with the next pull request, will build a pull request preview and insert a link to the preview in your pull request.
Note
It's currently not supported to check for a unique slug on Read the Docs before generating your project, especially if you set up a private repository.
We welcome contributions to cookieplone-templates.
You can create an issue in the issue tracker, or contact a maintainer.
See Installation.
For source control through Git and continuous integration and delivery (CI/CD), you'll also need a Git repository either under your personal or organization's account. Both GitHub and GitLab are currently supported Git repository and CI/CD service providers. However, only GitHub is currently supported for documentation hosting.
Create a local Python virtual environment with the following command.
make installCOOKIEPLONE_REPOSITORY=~/YOUR_PATH_TO/cookieplone-templates uvx cookieplone project --no-inputCOOKIEPLONE_REPOSITORY_TAG=<REMOTE_BRANCH_NAME> uvx cookieplonemake formatmake format_templatespytest is this package's test runner.
Run all tests with the following command.
make testRun all tests, but stop on the first error and open a pdb session with the following command.
uv run pytest -x --pdbRun only tests that match test_template_has_required_keys with the following command.
uv run pytest -k test_template_has_required_keysRun only tests that match test_template_has_required_keys, but stop on the first error and open a pdb session with the following command.
uv run pytest -k test_template_has_required_keys -x --pdbReleases of cookieplone-templates use CalVer versioning in the format YYYYMMDD.N, where N is a sequential counter that disambiguates multiple releases on the same day (e.g. 20260319.1).
Each release:
- Generates and commits a changelog from towncrier news fragments.
- Creates a Git tag matching the version.
- Publishes a GitHub release with the changelog as its body.
Before releasing, preview what the changelog will look like without making any changes:
make changelogWhen ready to release, run:
make releaseThis will:
- Determine the next CalVer version.
- Show a changelog preview and prompt for confirmation.
- Generate and commit the changelog.
- Push the tag to the remote.
- Create the GitHub release.
Note
A valid GITHUB_TOKEN with write access to the repository must be present in your environment.
This project is licensed under the MIT License.
Happy coding!