Templates
In Craft, you define your site’s HTML output with templates.
Templates are files that live within your templates/
folder. The structure of this directory is completely up to you—but keeping it organized and in agreement with project config settings is essential.
Craft uses Twig (opens new window) to parse your templates. Twig is elegant, powerful, and blazing fast. If you’re new to Twig, be sure to read the Twig Fundamentals page to familiarize yourself with its syntax.
PHP code isn’t allowed in your templates, but Craft provides various ways to extend Twig to suit your needs.
# Template Paths
There are several times when you’ll need to enter a path to one of your templates:
- When choosing which template entry and category URLs should load
- When assigning a template to a route
- Within include (opens new window), extends (opens new window), and embed (opens new window) template tags
Craft has a standard template path format that applies to each of these cases: a Unix-style file system path to the template file, relative from your templates/
folder.
For example, if you have a template located at templates/recipes/entry.twig
, the following template paths would point to it:
recipes/entry
recipes/entry.twig
# Index Templates
If you name your template index.twig
, you don’t need to specify it in the template path.
For example, if you have a template located at templates/recipes/ingredients/index.twig
, the following template paths would point to it:
recipes/ingredients
recipes/ingredients/index
recipes/ingredients/index.twig
If you have templates located at both templates/recipes/ingredients.twig
and templates/recipes/ingredients/index.twig
, the template path recipes/ingredients
will match ingredients.twig
.
# Hidden Templates
Craft treats templates with names prefixed with an underscore, for example recipes/_entry.twig
, as hidden templates that are not directly accessible.
If we have a recipe entry that is available at the entry URL http://my-project.tld/recipes/gin-tonic
, which uses the template located at recipes/entry
, someone could access the template directly at http://my-project.tld/recipes/entry
.
In this example there is no reason to access the template directly because it’s only ever used as part of an entry URL. We change its filename to _entry.twig
so it is considered hidden by Craft and update the settings in our Section.
Now when we try to access http://my-project.tld/recipes/entry
Craft returns a 404 error instead of attempting to render the template.
# Template Localization
If you’re running multiple sites with Craft, you can create site-specific subfolders in your templates/
directory, with templates that will only be available to a specific site.
For example, if you want to create a special template welcoming your German customers (but there’s no need for it on your English site) then you could save it in templates/de/welcome.twig
. That template would be available from https://example.de/welcome
, assuming the German site’s base URL is https://example.de
and its handle is de
.
Craft will look for localized templates before it looks for templates in the normal location, so you can use them to override non-localized templates. See our Localization Guide for more details.