Creating a custom home page

Creating a custom home page for your site is a great way to set yourself apart from the crowd and put your own unique stamp on your online presence. This tutorial shows you how to customise and develop your own custom home page in Ghost.

Creating and customising your template

Before we dive in there's a couple of prerequisites I'd like to explain for working with Ghost themes. Themes in Ghost use Handlebars, a templating language that provides access to Ghost content and other common templating benefits.

Theme file structure and index.hbs file

Every Ghost theme comes with an index.hbs file, the "hbs" stands for handlebars. This file renders all your posts, and is most likely being used on the home page of your site.

Download theme UI in the Ghost admin

By downloading your Ghost theme you can make changes to this file. To download the theme navigate to the Design view in the Ghost admin and scroll down to the selected theme and click "download" on the right hand side. Once you've unzipped the theme you can open the index.hbs file in a text editor and begin making changes.

{{!-- Main --}}
<main id="main">

        <h2>Hey 👋</h2>
        <p>My name’s Dave. I’m a Web Designer and Front-end Developer based in Bristol, currently working at Ghost as Developer Advocate.</p>
    {{!-- Featured Post --}}
    {{#is "home"}}
    {{#get "posts" filter="featured:true" limit="1" as |featured_post|}}
        {{#foreach featured_post}}
            <article class="post featured">
Snippet from a customised index.hbs file

In the above example I've added a short bio to the header. After making changes, zip the theme folder up and use the 'Upload a theme' button at the bottom of the Design view to upload your zipped theme.

A customised home page

But what if I want a more bespoke home page? The theme I'm using has pagination and those paginated pages use the same index.hbs template to list older posts, so my bio is going to be shown on all those pages too.

Home page with paginated pages beside them with the same content

We can prevent that from happening by creating a new template in our theme called home.hbs. You'll need to create this file in the root of your theme, at the same level as the existing index.hbs file. This new home template will replace the existing index.hbs template but only on the home page.

Once again you'll need to zip up the the theme, upload it to Ghost and activate it for the changes to take affect.

Same 3 pages but now with custom content only on the home page

Rendering Ghost content

As mentioned before, the handlebars templating lets us render content anywhere in a Ghost theme. For my use case I'd like to create a page called "Howdy " and render that content on my home page. With the use of Routes in Ghost it's possible to designate content data and templates to any URL in the site.

Post settings UI in the Ghost admin

First create a page in Ghost admin with your home page content and set the slug to "home", this will be the unique identifier to reference in your routes file. Next navigate to the Labs view and download your routes.yaml file from the Routes section. After opening it in a text editor it should look something like this:


    permalink: /{slug}/
    template: index

  tag: /tag/{slug}/
  author: /author/{slug}/

Amend the routes section to the following:

    data: page.home
    template: home

The / represents the root home page of the site and we're assigning the data which is the page we made with the slug "home", and we're assigning a template which is home.hbs. After you have made your changes save the file and upload the routes.yaml file to the same section within the Labs view of the Ghost admin.

Download / upload routes.yaml UI in the Ghost admin

Finally we need to render the home page content in the template with the use of handlebars theme helpers. Open the home.hbs template in a text editor and locate the area you want to insert your page content. Use the {{#page}}...{{/page}} helper to surround the area you want to add content to. Here's an example of my home template:

{{!-- Main --}}
<main id="main">
Snippet from a custom home page template

Save these changes, zip the theme up, and upload it to the Design view in the Ghost admin. You'll now have a custom home page that you can edit from right in side the Ghost admin!

Home page with custom content from page content

Adjusting page routes

A common pattern when creating a custom home page is to move the page where all your posts are listed to another page. To change where your post list gets rendered re-open your routes.yaml file and locate the collections section. Collections represent groups of posts, the default being all posts.

Amend the collections section to the following:

    permalink: /blog/{slug}/
    template: index

Similar to setting the home page data before we're selection the "/blog/" URL and allocating the default collection to that URL, we're also adjusting the permalink of the singular posts to be prefixed with "/blog/" to ensure a consistent URL pattern.

Home page and blog page showing their new respective content


Nice work! You've figured out how to create a custom home page for your Ghost site, where you can render any content and design required from your theme.

There's many ways in which you can extend on the concepts shown above. Check out our documentation on handlebars theming as well as how to allocate data and templates to routes using the routes yaml file. Plus you can get involved with our developer community by joining our official forum. ✌️