Why a stock theme slows down a Grav project
A stock Grav theme is almost always built "for everything at once": dozens of Twig templates, inheritance through several levels, plugins that pull in their own stylesheets and scripts on every page. While there is little content, this goes unnoticed.
As soon as the catalog grows to hundreds of pages, and dozens of blocks are added to a page, the CMS bottlenecks start to show: the template inheritance chain gets longer, and every render passes through all the intermediate layers, even if the resulting block is not output.
A separate problem is uncontrolled file system access. A ready-made theme reads configuration, page metadata, and media through several layers of abstraction, and on every request this is repeated from scratch.
With out-of-the-box caching, such calls are partially suppressed, but as soon as you enable dynamic blocks or personalization, Grav's performance drops precisely on repetitive operations, not on the render itself.
The third is dependencies. A theme pulls in a library for the sake of one function, a plugin includes its own version of the same library, and the final build ends up with duplicates.
This is not only extra page weight, but also conflicts during updates: it is unclear what can be touched and what will break the layout. The client ultimately pays longer for every edit, because the developer first has to untangle someone else's structure.
A custom Grav theme removes this at the architecture level: Twig templates are designed for specific page types without unnecessary levels of inheritance, file access is cached deliberately, and dependencies are pinned and minimized.
We break down how this is handled in turnkey Grav theme development — from template structure to the update policy.
What a Custom Theme Delivers: Measurable Impact
A custom Twig theme is built around a specific content structure rather than being bent to fit it. This delivers four measurable areas of gain: page delivery speed, update predictability, reduced support load, and content manageability for the editor. Below is how each one works and why.
Delivery Speed and Page Build Time
The theme compiles into Twig templates that Grav caches: re-rendering a page happens without re-parsing the markup. Heavy blocks — catalog, filters, forms — are moved into separate templates and loaded on demand rather than assembled in full on every request.
In practice, page build time drops from seconds to tenths of a second, and stable response time directly affects visitor behavior and search rankings.
Update Predictability and Failure Class
Grav core and third-party plugins are updated independently of your theme — an update doesn't break the layout or output logic.
A dedicated template layer eliminates an entire class of failures that arises when editing someone else's extension drags in incompatibility with the rest of the site.
Rolling back to a previous theme version restores a working state in minutes, without restoring the entire database.
Reduced Support Requests and Content Management
The editor works with clear fields and blocks instead of editing markup: standard pages are assembled from ready-made sections, and invalid input is filtered out at the template level.
The number of "fix the text and image" requests drops severalfold, and support cost becomes predictable — content edits don't require a developer. We work on Grav and the current Twig branch, so the theme remains compatible with core updates.
Approaches to theme development: comparing the options
Choosing between a ready-made theme, modifying an existing one, and building from scratch is not a matter of taste, but a question of which constraints you are willing to accept. Below is an honest comparison across the three scenarios clients most often come with.
| Option | When it fits | Constraints |
|---|---|---|
| Ready-made theme from a catalog | You need a quick start: a landing page, a blog, a typical corporate site with a predictable structure | The design and markup are set by the theme's author; non-standard blocks and output logic require workarounds, some of which run up against the template architecture |
| Modifying an existing theme | The site is already running, the content structure is established, and you need targeted changes: new page types, blocks, integrations | You inherit someone else's conventions for templates and styles; the deeper the edits, the higher the risk of conflicts when the theme is updated |
| Custom theme from scratch | A unique content structure, your own page types and collections, requirements for speed and markup | Longer implementation timelines: first designing templates and types, then coding and populating |
A ready-made theme wins on implementation timelines, but loses where the content structure does not match the author's intent.
Modification is a reasonable compromise as long as the edits are local: once the output logic changes across most pages, maintenance becomes more expensive than building clean.
A theme from scratch pays off when the content model is non-standard: your own page types, collections, reusable blocks.
Here the markup and templates are designed for the task rather than forced into someone else's grid — and that is what delivers predictable maintenance down the line.
We analyze the content structure and page requirements, after which we say it straight: where a ready-made solution is enough, where modification is needed, and where it is more honest to build a theme from scratch.
How we develop a Grav theme: stages
We run Grav theme development as an engineering project with fixed stages: each step ends with an artifact that can be verified before moving on to the next.
This way requirements don't "blur" along the way, and template inheritance and content structure are designed before the first line of markup — rework in the middle costs more than an audit at the beginning.
Seven stages of work
- Requirements audit. We break down page types, blocks, modules, and editor scenarios: what is filled in manually, what is assembled from collections, where reusable fragments are needed. The output is a content map and a prioritized list of templates.
- Template and inheritance scheme. We design the tree of Twig templates: base framework, partials, overrides by page type. We fix which block is inherited and which is overridden — this eliminates markup duplication.
- Environment setup. We set up a local staging environment, a repository, and a build for styles and scripts, and configure draft and production contours. Edits go through branches, not directly on the live site.
- Component assembly. We build sections, forms, navigation, and media blocks on the real content structure, not on placeholders. We check each component for responsiveness and behavior with empty data.
- Markup verification. We run pages at different resolutions and browsers, compare against the design, and check accessibility and load speed. We close errors before handover, not after launch.
- Editor training. We show how to add pages, assemble blocks, and change content without a developer. We provide a short guide for typical actions.
- Project handover. We hand over the repository, configuration, template documentation, and access credentials, deploy on the production contour, and fix the update regulations.
After handover, the theme remains maintainable: the template structure and inheritance rules are documented, so new blocks are added predictably. Describe your task — we'll come back with an estimate and a stage-by-stage plan.
Theme structure, Twig templates, and inheritance
A theme in Grav is not a set of separate pages, but a hierarchy of Twig templates with a clear inheritance order. The base base.html.twig describes the framework: connecting styles, meta tags, common blocks.
Child templates inherit it via {% extends %} and override only the necessary blocks — {% block content %}, {% block header %}. This way, an edit in one place propagates across all pages, rather than requiring manual traversal of dozens of files.
Repeating elements — menu, footer, product card, subscription form — are moved into partials and connected via {% include %} with parameter passing.
The same block is used on the homepage, in the catalog, and in an article, so layout discrepancies between sections are eliminated technically, rather than through developer discipline.
A separate layer is the blueprint configuration. For each page type, a set of fields is described: title, image, text blocks, gallery, repeating sections. The editor fills them in through the admin panel, and the template assembles the page from this data.
Adding a new block or changing the order of sections can be done without editing code — the developer gets involved only when the output logic itself changes.
Such a theme structure provides predictable maintenance: a new section is assembled from ready-made partials in hours, rather than rewritten from scratch.
Templates remain readable because each is responsible for its own area of responsibility, rather than mixing markup, data, and logic in a single file.
What the client receives upon handover
Handover is not an archive of files, but a package your team can use to work without us. A Grav theme lives as source code and configuration, so we hand over both: without understanding which template is responsible for what, any edit turns into code archaeology.
- Theme source code — a full repository with change history: Twig templates, styles, scripts, inheritance scheme. Deploys with a single command on a clean environment.
- Template map — a correspondence chart: which Twig file renders which page, which parent it inherits from, where blocks and partials are connected. With it, a new developer gets oriented in an hour, not a week.
- Configuration files — blueprints and theme settings: which fields are available to the editor, which default values apply, where texts and media are stored. Content edits do not require code edits.
- Editor guide — how to add a page, change a block, upload an image, what to do on an error. Written for a person without a technical background, with screenshots of real screens.
- Update policy — the procedure for updating the Grav core, plugins, and dependencies: what is checked beforehand, how a rollback is done, which branches are considered stable. Updating stops being a risk.
- Inspection log — the acceptance protocol: which scenarios were tested, on which browsers and resolutions, which issues were closed. It is clear what exactly was checked, rather than "it seems to work."
Plus access to the repository and environment, pinned dependency versions, and contacts for questions during the support period. All of this is described in one place — no need to gather knowledge from chat threads. Describe your task — we will come back with an estimate and a handover plan.
Case study: migrating a catalog to a custom Grav theme
The customer's catalog on Grav — an equipment manufacturer — ran on a theme assembled from an off-the-shelf template with a dozen extensions. Every markup change pulled a chain of dependencies along with it, and the editor could not publish a new section without a developer.
We migrated the catalog to a custom theme turnkey: our own Twig templates, a unified set of blocks, and product card fields moved into configuration.
What we changed
We built the theme from scratch around the catalog structure: separate templates for categories, cards, and landing pages, a shared component layer instead of duplicated markup.
The editor got ready-made blocks — a gallery, a specifications table, a documents block — and assembles a page from them through the control panel, without touching code.
Heavy images were moved to lazy loading, and static assets are served through cache rather than through a handler.
Metrics before and after
| Metric | Before | After |
|---|---|---|
| Catalog page response | 1.8–2.4 s | 0.4–0.6 s |
| Support requests about markup | 12–15 per month | 2–3 per month |
| Publishing a new section by the editor | 2–3 days via a developer | 30–40 minutes independently |
| Editing a product card | through code | through the control panel |
We also took load off the team separately: routine tasks — a new section, a banner, a change to the catalog structure — the editor handles on their own. Developers get back to product tasks instead of markup edits.
If your catalog is hitting a wall on response speed or your editor depends on a developer — describe the task, and we will come back with an estimate and a migration plan.
How is a custom theme different from modifying a ready-made one?
The difference is not in the scope of work, but in where the boundary of applicability lies. A ready-made theme is an architecture someone has already adopted: its own Twig template hierarchy, its own partial blocks, its own inheritance conventions.
Modification is cheaper and faster as long as the task fits within that architecture: change a block's markup, add a section to the homepage, override a single template through the inheritance mechanism. As long as the edits are local, you pay for hours and get results in days.
Modification turns into constant patching when requirements start to conflict with the built-in structure. A typical sign: to add a single page, you have to touch five templates, and every theme update overwrites your edits, which then have to be migrated all over again.
The second sign is the content model. If page types, taxonomies, and fields are defined in the theme rather than in configuration, an editor cannot assemble a new page without a developer.
A custom theme is when we design the template structure around your content model, rather than bending the content to fit someone else's.
Inheritance is set up so that a new page type is added with a single template and a set of partial blocks, and the query logic lives in configuration rather than in markup. Then editing content does not require a release, and updating the core does not break the layout.
The boundary of applicability is calculated by cost of ownership, not by the price of the first version. Modification wins over a short horizon and a narrow set of edits.
As soon as edits become regular and theme updates become a risk, the total support costs overtake building from scratch, and the moment for a rewrite arrives.
A rewrite is not a redo of the markup, but a migration of the content model and routes onto a new template structure; the earlier it is done, the less it costs.
Common technical concerns from clients
Before the start, almost every team asks the same set of questions — and these are the right questions, because the answers to them determine what the site will turn into after a year of operation. Below is how we address each of them at the architecture level, not with promises.
What will happen with core updates, and will they break the theme?
The theme is installed as a separate package and does not patch the core — a system update does not affect templates or styles.
Custom logic is moved into its own extensions and Twig template overrides via inheritance, so a standard update proceeds without changes to the theme code. We pin a compatible core branch and test the update on a staging environment before moving it to the production environment.
What about plugin compatibility?
We do not drag in a dozen third-party extensions: typical tasks — forms, menus, search, media output — are handled by our own code in the theme.
If a plugin is still needed, we check it for conflicts with templates and access rights, and move its settings into the project configuration. This way, updating one extension does not bring down the rest of the site.
How is content migrated from the old site?
We migrate content with a script: we parse the page structure, transfer texts, media, and metadata into the new templates, preserving URLs or setting up correct redirects. After the migration, we verify the page tree and the link map so as not to lose search positions. Editors receive an already populated site, not an empty skeleton.
What is included in support after delivery?
We hand over the repository, environment configuration, and deployment instructions, and establish the update and backup regulations. After that, we provide maintenance: template edits, block enhancements, incident resolution. Rolling back to a previous version is possible at any time — the full change history is stored.
Will an editor be able to work with the site without a developer?
Yes, and this is built into the structure in advance: content is edited through clear fields and modular blocks that are assembled into a page without layout work. We train editors on their own content and leave a brief guide for typical scenarios. The developer gets involved only for new block types.
Describe your task — we will get back to you with an estimate and a work plan for the theme.
Let's discuss your theme development task
To come back with an estimate and a plan rather than generalities, we need a minimum of input. The first conversation takes 20-30 minutes and is to the point: what the project is, which pages and content types are involved, who will handle content after launch.
Based on the results, we say whether the task fits into a custom Twig theme or whether part of it can be covered by out-of-the-box tools — that's more honest than dragging everything into development.
What to send for an estimate
- A link to the current site or prototype — even a draft one, if it exists.
- A list of page templates: home page, catalog, product page, blog, forms, account area.
- A content schema: which post types and fields the editor needs, what they should be able to change themselves.
- References: 2-3 sites where you like the structure or block behavior, noting exactly what.
- Integration requirements: CRM, payments, newsletters, external services — as a list, without implementation details.
- Constraints: deadlines, being tied to existing hosting, security or accessibility requirements.
How the first conversation goes
We break down the task by templates and content types, not by "make it look nice." At this stage, bottlenecks surface: non-standard fields, complex output logic, migration of existing content.
If some requirements conflict with each other, we'll say so directly and propose an option that solves the original task more simply.
After the conversation, we come back with a project estimate, a phased work plan, and timelines. The plan shows what's done first, where your decisions are needed, and at what point you can review an intermediate result.
If the task changes during the discussion, we rebuild the plan rather than clinging to the old estimate.
Describe the task in whatever form is convenient — we'll come back with an estimate and a work plan.
