Creating templates and editing routes
Templates & structure explains what a template is. This page is about adding one of your own and about the routes some of them create.
Add a template
There are two Add buttons, and they do different things.
The Add button at the top of the Templates list opens Add Template, a list of ready-made templates to add: recommended pages such as About and Contact, recommended collections, Error pages, and any default template the project does not have yet. Your first Custom template is offered here as well, and disappears from the list once the project has one.
To build a template yourself, use the Add button on the group row the template belongs to: posts, pages, tags, authors, or collections. Custom templates get a row of their own only after the first one exists, and then that row carries the same button. Each offers these forms:
- Page for specific slug and Post for specific slug. One page or one post gets its own design, matched by its Ghost slug.
- Page by tag and Post by tag. Every page or post carrying an internal tag gets the same design. Use this when the set will grow.
- Custom template. A named template a Ghost editor can pick by hand from the post or page settings.
- Tag for specific Slug and Author for specific Slug. One tag archive or one author archive gets its own design.
- Custom collection. A section of the site with its own URL path, such as
/resources. Create matching post template adds a post design for the posts inside it at the same time.
Error templates have no form of their own. Add them from Error pages in the top-level Add Template list.
What each becomes in the ZIP
A slug template becomes its own file, such as page-about.hbs. A custom template becomes custom-narrow.hbs, which is the name Ghost shows to editors. An error template becomes error-404.hbs.
A tag template is different. It becomes a partial under partials/templates/, because Ghost has no filename convention for "posts carrying this tag" and Fantasma routes to it instead.
Which templates change routes.yaml
Only collections and the tag and author archive paths reach routes.yaml. Slug, tag, custom, and error templates are all matched by Ghost from the filename, so they need no route file.
That is why adding a page template changes nothing outside the ZIP, and adding a collection asks you to upload routes.yaml as well. See routes.yaml for the upload.
Edit a route after the fact
A collection's route is not fixed at creation. Open Collection settings from the template's context menu to change its Path, its Post permalink, and the Internal tag that decides which posts belong to it.
Tag settings and Author settings do the same for the archive paths, where you edit the Slug that sits in the URL.
Every one of these rewrites routes.yaml, so upload the new file to Ghost after changing them.
Download or publish again
A new template is a theme change. Download a new ZIP or publish, and upload routes.yaml when the builder says routes changed.