Zotonic Coding
Developmentzotonic-codingZotonic Coding is an Agent Skill for development published in the zotonic/zotonic repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when working in Zotonic projects, especially Erlang modules, Zotonic template_compiler templates, dispatch rules, site templates, logging, datamodel fixtures, or site/module structure. Provides project conventions for pragmatic Zotonic 1.x coding.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/zotonic/zotonic/blob/HEAD/.agents/skills/zotonic-coding/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/zotonic-coding, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Zotonic Coding
First Pass
- Read the local app/module before editing. Prefer existing project patterns over inventing new abstractions.
- Keep changes inside the requested app unless the user explicitly expands scope.
- Files use UTF-8 and LF line endings.
- Use
rg/rg --filesfor discovery. - Prefer
makefor normal Zotonic builds; use./rebar3 compileafter Erlang changes when you only need a compile check. Ignorerebar.lockchanges from normal build/test commands unless the task intentionally changes dependencies.Ignoreerl_crash.dump; it is already in.gitignoreand should not be reported as actionable worktree noise.
Erlang Style
- Prefer pattern matching and small functions over nested conditionals.
- Use maps for structured request/payment/API data in Zotonic 1.x.
- Add
-specdeclarations using named variables andwhenclauses:
-spec function_name(Arg, Context) -> Result
when
Arg :: binary(),
Context :: z:context(),
Result :: ok | {error, term()}.
- Use
#trans{ tr = [...] }records, not old{trans, ...}tuples. - Use Zotonic records such as
#datamodel{}and#rsc_tree{}when fixtures/menu structures require them. - Use
m_site/context environment data for environment-dependent behavior instead of duplicating dev/prod fixtures. - For Zotonic 1.x code, expect request keys, query keys, JSON keys, and most external textual data to be binaries, not strings.
App Structure
- Zotonic is an Erlang umbrella application. Core modules live in
apps; user modules and sites live inapps_user. - Each module/site is an Erlang application with a
src/*.app.src. - Module application names must start with
zotonic_mod_...; the main Erlang module is usuallymod_name.erl, for examplesrc/mod_payment_buckaroo.erl. - Sites use a site module such as
src/nom.erland must have apriv/zotonic_siteconfig file, using.config,.json,.yaml, or.yml. - Module/site roots should have
rebar.configunless the local workspace has an established exception. - Common source directories include
actions,filters,scomps,validators,models,controllers, andsupport. - Actions, validators, and scomps should include the module/site name in their Erlang module name so higher-priority modules can override them cleanly.
- Keep the main
mod_*.erlfocused on Zotonic module concerns:-mod_*declarations, lifecycle hooks, observers, dispatch/menu setup, datamodel/install hooks, and small glue code. - Put template/model-facing APIs and site-aware operations in
src/models/m_*.erl. Models are the right place to normalize input from templates, check ACLs for model data, read module config, start shared workers when needed, and expose stable functions to other Zotonic code. - Put reusable implementation details in
src/support/. Support modules should own focused domain logic, parsing/recombination, protocol handling, workergen_servers, and helpers that are not themselves template APIs. - Prefer the model as the boundary between Zotonic callers and support processes. Keep process startup, batching, timeouts, and result normalization close to the public model API unless the logic is truly generic.
Logging
- Prefer structured
?LOG_*maps. - In
?LOG_*maps,in => ...is the Zotonic module or Erlang application context, not necessarily the current Erlang?MODULEfile. - If logging
?LOG_ERRORwithresult => error, includereason => .... - If logging after an operation that returns
ok | {error, Reason}, branch on the result and log success/failure explicitly. - If a module already includes
zotonic_core/include/zotonic.hrl, do not also includekernel/include/logger.hrl;zotonic.hrlprovides the logging macros.
Templates
- Zotonic templates use
template_compilertags, loosely Django-like. - Documentation for the tags is in doc/template-tags
- Use
{% extends "base.tpl" %}and blocks for page composition. - Use
{% catinclude %}for category-specific page/header variants. - Prefer resource URLs with
m.rsc.resource_name.page_urlfor named resources. - Prefer
{% url dispatch_name %}for controller/dispatch URLs. - Avoid hard-coded internal URLs.
- Resource names do not contain spaces; Zotonic replaces spaces with
_. - Use
{% all include "_html_head.tpl" %}and standard Zotonic body includes instead of directly including module-provided_html_head*fragments. - Do not duplicate Google Tag Manager or SEO head/body snippets that are provided by Zotonic modules such as
mod_seo. - Favor semantic HTML and accessibility: use
header,nav,main,section,article,footer; addaria-*where appropriate; provide useful imagealttext. - Use lowercase HTML tags and attributes.
- Avoid excessive wrapper
divs and inline styles. - Prefer Zotonic template constructs (
{% block %},{% if %},{% for %}, etc.) for logic. - Do not directly display values from
qin{{ ... }}unless they are escaped or sanitized. - Values from
m.rscare sanitized and may be displayed directly. Values from other models are not guaranteed sanitized and must be escaped or otherwise sanitized. - Files in
priv/templates/staticare served as-is. A.tplfile in that directory must still be a valid template. priv/templates/mediaclass.configdefines image mediaclasses usable in{% image %}tags and is written in Erlang format.
Translations
- Keep template source strings in English. Replace Dutch or other source-language literals with English sentences.
- Wrap user-facing static text in translation tags:
{_ English source text _}
- For include arguments or template variables that should be translated, use translated values such as
title=_"Important pages". - Do not regenerate or commit POT files during normal feature work. Zotonic POT files are generated on the
masterbranch with:
bin/zotonic pot zotonic
- The POT command connects to the running Zotonic node. If a feature/test command creates POT diffs, restore or leave them out unless the user explicitly asks to update POT files.
- POT files live under
priv/translations/templatefor sites and under core/module translation directories for Zotonic modules. - Merge existing PO files with gettext:
msgmerge --backup=none --update priv/translations/nl.po priv/translations/template/site.pot
- Add a new language with
msginitand then fill useful translations:
msginit --no-translator --locale=de --input=priv/translations/template/site.pot --output-file=priv/translations/de.po
- Validate PO syntax with:
msgfmt --check --output-file=/dev/null priv/translations/nl.po
msgfmt --check --output-file=/dev/null priv/translations/de.po
- A practical final check is an
rgscan for known Dutch words inpriv/templates, but avoid matching compiled libraries or unrelated assets.
Dispatch
- Zotonic handles language prefixes in page paths; do not add language-code-specific dispatch rules for normal pages.
- Keep dispatch rule names language-neutral.
- Do not create dispatch rules for named page resources that can use
page_path/m.rsc.name.page_url.
Frontend Assets
- Static compiled output belongs in
priv/lib. - Source assets such as SCSS belong in
priv/lib-src. - CSS builds should be driven by a local Makefile in
priv/lib-src, with the app-levelMakefiledelegating to it. - Keep Taskfile targets focused on the app-level Makefile; remove obsolete Elm build targets after migration.