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

Use the Add button at the top of the Templates list. It offers five 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 are not created here. Add them from the recommended pages list in the same sidebar.

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.

Related articles