README

Template Paths Plugin for Craft CMS

See which Twig template rendered every part of your page.

Template Paths is a free plugin for Craft CMS that marks up your rendered HTML with comments naming the template, block and macro responsible for each region of the page. When you are looking at a component in the browser and cannot tell which of forty includes produced it, view source and the answer is right there.

It runs in devMode only, and adds nothing at all to your site anywhere else.

<!-- BEGIN _layout/_base.twig -->
  <!-- BLOCK BEGIN content / _layout/_listing.twig -->
    <!-- BEGIN _includes/_header.twig -->
    <!-- END _includes/_header.twig -->
    <!-- MACRO BEGIN card / _macros/_cards.twig -->
    <!-- MACRO END card -->
  <!-- BLOCK END content -->
<!-- END _layout/_base.twig -->

There is nothing to learn and nothing to switch on. Install it, and the comments are there.

Requirements

This plugin requires Craft CMS 5.5.0 or later, and PHP 8.2 or later.

Installation

To install the plugin, search for "Template Paths" in the Craft Plugin Store, or install manually using composer.

composer require moca-nz/craft-template-paths
php craft plugin/install template-paths

Usage

Load any front-end page with devMode on and view the page source.

Templates are marked with BEGIN and END, naming the template path.
Blocks are marked with BLOCK BEGIN and BLOCK END, naming the block and the template that defined it. Blocks are marked on every render path into them, including {{ block('name') }}, {{ parent() }} and {% embed %} overrides.
Macros are marked with MACRO BEGIN and MACRO END, naming the macro and the file it lives in.

The control panel is never touched, and neither are string templates such as SEO titles or entry title formats.

Settings

There is one setting, and it is off by default. To restrict the comments to logged-in users, copy the plugin's config.php into your project as config/template-paths.php:

<?php

return [
    'requireLogin' => true,
];

The value may also be an environment variable, for example '$TEMPLATE_PATHS_REQUIRE_LOGIN'.

This setting is read when Twig compiles a template rather than on every request, so after changing it you need to clear the compiled templates:

php craft clear-caches/compiled-templates

That is also the trade: while the restriction is off, the compiled templates contain no check at all, so it costs nothing per request instead of running for every comment on every page.

Caveats

Comments land inside the region they wrap. A {% block %} inside <title>, or a macro that builds an HTML attribute value, will have comments injected into it. Likewise, a block captured into a string with {% set x = block('y') %} captures its comments.
Uninstalling does not clear compiled templates. Twig only recompiles when it needs to, so removing the plugin can leave already-compiled templates still emitting comments. Run php craft clear-caches/compiled-templates afterwards.
devMode is the only gate. If an environment you think of as "not local" runs with devMode on, it will render these comments.

License

This plugin is licensed for free under the MIT License.

Created by MOCA.

moca-nz / craft-template-paths

Package info

Security

Statistics