Custom Pico CMS Theme: Where Standard Markup Breaks
The standard Pico CMS theme is designed for a uniform structure: one column, a menu, a list of materials. As long as pages are the same, the templates fit without resistance — content lives in markdown files, and the templating engine substitutes values from their metadata.
But as soon as non-standard markup appears — blocks of different widths, nested sections, repeating modules with different sets of fields — the stock templates begin to dictate the page structure rather than the other way around.
The first bottleneck is the limitations of the templating engine: inheritance and includes exist, but there is no separate data layer.
Everything that does not fit into file metadata has to be calculated directly in the template, and the same markup is duplicated in a dozen places.
Any edit to a block turns into a pass through all templates where it occurs, and discrepancies between copies surface already in production.
Second — edits in the engine core. This is the fastest way to achieve the desired behavior, so it is usually where people stop: they override handlers, add logic to core files, substitute output.
After that, an update stops being an update — patches are transferred manually, some changes are quietly lost, and the engine version freezes at the one where everything still converges.
The cost of such a scheme is diverging markup on non-standard pages and loss of version control. We'll break down how this is closed: logic moves out of the core into the theme, data gets an explicit contract, and markup is assembled from modules that can be changed separately.
What a Dedicated Theme Delivers: Speed of Publishing and Edits
A reworked template layer means page markup is not written by hand but assembled from the content description.
The author fills in fields at the beginning of the file and text in lightweight markup, and the theme inserts them where needed: title, header, card grid, related materials block.
The Twig templating engine provides template inheritance and macros for this — one framework for the entire site and separate fragments for each block type.
Because of this, publishing a typical page is not markup from scratch but copying a template and editing fields: dozens of minutes instead of hours, and this time does not grow with the number of pages.
When the card structure changes, the edit goes into one fragment and propagates across all sections at once — previously such changes went through each page separately, and some of them inevitably lagged behind.
Reusable blocks also remove an entire class of markup failures: unclosed containers, broken grids, different paddings in identical blocks. The markup is formed by the template, so it is the same on all pages and does not depend on who laid out the next section and when.
Content edits stop being a reason for downtime.
Text and metadata live separately from code, the theme assembles them into a finished page, so an editor publishes material without deploying a new build, and if a template does change, it is checked on a test copy of the site before being transferred to production.
Customization Approaches: Child Theme, Core Fork, Custom Layer
A theme in Pico CMS is a set of Twig templates plus a settings file: the core serves content, and templates decide how it looks. Therefore customization is not a question of syntax but of what happens to edits during the next engine update.
| Path | When It Fits | What Limits It During Updates |
|---|---|---|
| Child theme (add-on) | Changing markup, styles, block composition; overriding individual parent templates | Cannot intervene in core logic: after the parent structure changes, overrides are reconciled manually |
| Core fork | Non-standard routing or a custom page-processing pipeline is needed | Every update requires manual transfer of edits; conflicts accumulate, security updates are postponed |
| Custom template layer | Long-term development, non-standard rendering, engine connected as a library | Higher barrier to entry: the team maintains compatibility with stock rendering itself |
In practice, a child theme covers most presentation tasks and survives updates without rewriting. A fork is used selectively — where the task cannot be solved otherwise, and then the core update is planned as a separate stage.
A custom layer is chosen when there are so many templates and logic that stock rendering becomes too tight.
Work Stages: Template Audit, Schema, Assembly, Verification
Work begins not with markup but with an audit: the new theme must fit the existing content structure, not require rewriting materials. The inventory takes from half a day and immediately shows where the client's expectations and the actual state of templates diverge.
- Template audit. We go through the theme directory, collect all markup files, mark inheritance chains, duplicate blocks, and fragments no one references anymore. The result is a dependency map and a risk list.
- Content and template schema reconciliation. We compare fields in page metadata with what the markup actually reads. We find fields without output and variables without a source: this is the main reason blocks "break" after a theme change.
- Schema design. We fix the base framework, reusable fragments, sets, and inheritance order. The schema is agreed before the first line of markup — edits at this stage are many times cheaper.
- Assembly. Markup is written according to the schema, repetitions are moved into shared blocks, and caching templates are configured so that the editor sees changes immediately and the visitor does not wait for a rebuild.
- Regression verification. We run typical pages, feed, search, pagination, forms, and social media metadata. Each path is checked before and after — discrepancies are recorded in a protocol.
- Theme handover. We provide a repository with history, comments in templates, and a schema description, and separately train editors: how to add a page, block, image without breaking the markup.
This order gives a predictable result: by the time markup begins, no controversial decisions remain, and after handover editors work with content without developer involvement.
What the Client Retains: Templates, Schemas, and Regulations
Our acceptance check is not based on "the site opens" but on whether the client's team can change any page and block without us. We verify the package below live: open the repository, edit test text, deploy, roll back.
- Theme source files — a repository with full change history, separate branches for stable and working lines, and instructions for local launch on a test environment.
- Template schema — a Twig inheritance map: which template is base, which blocks override nested ones, and where each fragment gets data from.
- Configuration map — where Pico CMS settings live, what changes at the environment level, and what will require template edits.
- Edit regulations — the order of changes: branch, test environment check, approval, deployment; who is responsible for release and how to roll back to the previous version.
- Content documentation — how to create a page, required metadata fields, markup rules, image storage and optimization.
- Design tokens — colors, paddings, and typography moved into variables: changing the brand style does not touch the template structure.
- Acceptance checklist — paths and scenarios with expected behavior, by which the client accepts edits themselves.
Support after handover does not have to remain with us: an engineer familiar with Twig can join the project using these documents. In practice, the client's team handles content and markup edits independently by the second iteration.
Case Study: Editors Publish Without Developer Involvement
A site on Pico CMS stores content in markdown files, so editors wrote texts themselves. Presentation lived separately: to place a quote block, change the order of sections, or add a banner to a section, one had to edit theme templates and wait for the developer. Each such edit went through a ticket, verification, and deployment.
Before the rework, seven out of ten changes on a page went through an engineer, and publishing material took three to four days: the editor prepared the text, then waited for markup. Support received about twenty requests per month, half of them about the appearance of pages.
What Was Changed
The theme was rebuilt as a set of ready-made blocks with limited settings: alignment, heading size, and number of columns are selected from a list rather than set manually.
The editor assembles a page from blocks and immediately sees the result — they cannot break the markup or lead it away from the brand style. Content files remained ordinary markdown, so the old markup was not lost.
What Changed
- Share of edits requiring a developer — from seven out of ten to one out of ten.
- Material publishing time — from three to four days to several hours within the workday.
- Markup-related support requests decreased threefold in the first month.
An additional effect is predictability: new blocks are added to the theme separately and do not affect already published pages. Content updates stopped being a bottleneck, and editors plan publications by calendar, not by markup readiness.
Technical Concerns Before the Start and Answers to Them
Before the start, clients ask the same questions: what will happen to a custom theme when the engine is updated, will it survive a migration to another server, and will indexed page URLs be lost.
Below are short answers for each point; if doubts remain for your case, we will address them at the estimate stage.
We design the theme so that its code is separated from the Pico CMS core: templates and styles live in their own folder, extensions are connected through stock mechanisms rather than edits in engine files. This is exactly what determines what subsequent updates and migration will cost.
What will happen to the theme when the engine is updated?
The update is installed on top: overrides in a separate folder do not conflict with the core, because we do not touch the core. Before that, we take backups and run the theme in a test environment — rollback if a problem occurs takes minutes.
How will migration to another server go?
Content and theme are transferred together with change history; no re-layout is needed. Only the path, write permissions, and web server settings change — we check them against a list so that nothing breaks after migration.
Will page URLs be preserved?
Yes, if the file structure and routing rules are changed consistently. When rebuilding sections, we set up redirects from old URLs and verify them against a list — search results and external links continue to work.
Who is responsible for template compatibility?
We are. Compatibility of Twig templates with the current engine branch is our responsibility: during an update, we check every template, fix outdated constructs, and record the procedure in the regulations so that the next update follows a proven scenario.
How Does a Template Override Differ from a Plugin?
A template override and a plugin are different extension points, and confusing them is expensive. The first replaces a theme file: Twig takes your version instead of the parent one, and data arrives in it already prepared.
The second subscribes to core events and intervenes in the request-processing order — before page output, during markup parsing, during menu assembly.
Processing order is set by subscription priority: the core calls plugins in a known sequence, so one plugin sees the result of another's work. A template does not fit into this pipeline — it receives what has already been assembled.
Hence the difference in conflicts: plugins can overwrite each other's data, while overrides compete only for the same file.
The choice between them comes down to what exactly changes:
| What We Change | Template Override | Plugin |
|---|---|---|
| Page layout and markup | Pointwise, by theme file | Extra layer |
| Data, routes, fields | No access to the source | Through core events |
| Request-processing order | Does not participate | Controls priority |
| Behavior during core update | Preserved | Compatibility check required |
| Behavior when theme changes | Lost | Preserved |
The practical rule is simple: if the output changes, override the template; if data or logic changes, write a plugin. Keeping both in one place means paying twice with every update.
When layers are separated, a core update does not overwrite the layout, and a theme change does not break functionality — extensions stop conflicting with each other.
What to Send for an Estimate: Source Data Composition
Estimating a Pico CMS theme depends not on the number of pages but on the state of the code and content.
When we have a copy of the site and a clear list of templates, we calculate the work based on facts, not guesses, and come back with a plan and timeline in one go, without a series of clarifying emails.
- Access to a copy of the site: a separate environment with the same set of extensions as production, plus access to theme files and the database if content is stored not only in text files.
- The current theme in full — archive or repository: Twig templates, partials, styles, scripts, service settings. Not an extract of "only what we edit": connections between templates are visible only in the full tree.
- A list of plugins and third-party embeds, marked which are critical. This immediately shows areas where logic will have to be rewritten for the new markup.
- Example pages by type: home, list, card, material, form, error page. 5–10 URLs are enough to estimate template inheritance and shared blocks.
- Environment constraints: PHP version and extension set, memory and execution time limits, caching scheme, static file delivery.
- Layouts and design sources if the theme changes visually — with mobile resolutions and element states.
- Invariants that cannot be lost during migration: page URLs, meta tags, microdata, redirect rules.
- Priorities: which sections are needed first, and what can wait until the next stage.
If something from the list is missing, it is not a blocker. Describe what you already have; we will gather the rest together on a call: we will discuss the task and come back with the scope of work, estimate, and plan.
