Custom Pages in Ghost CMS Themes

Pages in Ghost CMS are basically a subset of posts, the difference being that they are excluded from all collections and feeds. Pages are intended for static and independent content, for example About or Contact page.

Create a Page in Ghost

1. Log in to your Ghost Admin Panel.
2. Under Pages click on New Page.
3. Enter a title and content for your page within the editor.
4. Open the Page Settings & click Publish

This way your page will be published and will be rendered using the default page.hbs template (or post.hbs if page.hbs doesn't exist).

If you want to have a custom layout for your page, there are three main ways to do this in Ghost:

1. Using the routes.yaml file
2. Using page templates
3. Using custom templates

Custom page with routes.yaml

The routes file is what defines the URL structure of your Ghost website and at the same time configures the different content collections and their URL.

If we are talking about a custom about page, then we need the following section in the routes.yaml file:

routes:
  /about/:
    template: about
    data: page.about

In the code above we do two things, we define the route /about/ (URL) based on the about.hbs template and with data coming from the page with slug about

The data property is not mandatory to define, but it's a great way to easily control all the meta properties from the Admin area for this particular page. You can also use other parts of the page like the feature image or content if needed.

To use the content of the page inside the about.hbs file, you have to be in the page context, for example to output the title and content:

{{#page}}
  <h1>{{title}}</h1>
  <div>{{content}}</div>
{{/page}}

In a similar way, you can create other pages like a custom contact page or a custom home page.

Custom page with page template

If you want to change the layout for a specific page, or simply want to adjust the default page.hbs template for another page, this method is quite fast and you don't need to change your website's routing.

In this method, the first requirement is to create the page in the Admin area and publish it. Going back to the about page example, you now have the page with the slug about.

The next step is to create the page template, in your theme create a new file called page-about.hbs in this file, you can add your own layout, whether it's a completely custom markup, or starting out from the default page.hbs file.

Custom page with custom templates

Custom templates are very useful when the layout you are looking to create can be used by multiple pages/posts. To create a custom template, you have to name it specifically: custom-{{template-name}}.hbs

Every custom template file name has to start with custom- then you can add some relevant naming for that template.

In Ghost Admin custom templates will appear in Post/Page Settings under Template. For example, I've created custom templates like these:

• custom-wide-post.hbs (Wide Post)
• custom-with-sidebar.hbs (With Sidebar)

Going back again to the about page example, you can potentially create custom-about.hbs with the layout you want, then in the Admin section, open the settings for your about page, and under Template, select About (or however you named the template).

My personal opinion is that custom templates should be used for layouts that could be used by multiple posts and/or pages.

Conclusions

We have covered three different ways to create custom pages in Ghost, all of them have advantages and disadvantages and you can use any of these depending on what you are looking to do.