tryghost / starter

A development starter theme for Ghost

Ghost Starter Theme

A starter framework for Ghost themes! Click Use this template to create a copy of this repo for everything you need to get started developing a custom Ghost theme.

 

First time using a Ghost theme?

Ghost uses a simple templating language called Handlebars for its themes.

We've documented this starter theme pretty heavily so that it should be possible to work out what's going on just by reading the code and the comments. We also have a robust set of resources to help you build awesome custom themes:

• The official theme documentation is the complete resource for everything you need to know about Ghost theme development
• Tutorials offer a step-by-step guide to building the most common features in Ghost themes
• The Ghost VS Code extension speeds up theme development and provides quick access to helpful info
• All of Ghost's official themes are open source and are a great reference for learning how to create a theme

 

Starter theme features

🔁 Livereload by default. See changes instantly in the browser whenever you save a file.

🔎 Optimized for VS Code. Find the files you're looking for more easily.

🗃️ Write modern JavaScript. Use ESM out of the box to write more manageable Javascript.

🗜️ Assets optimized automatically. JavaScript and CSS are minified and transpiled by default.

👟 Fast compile times, powered by Rollup.

🦋 Write next-gen CSS for today's browsers with PostCSS. Add the CSS tools you love via rollup.config.js.

🚢 Ghost's GH Deploy Action included by default. Learn more how to deploy your theme automatically

➕ Extensible by design. Rollup's configuration structure makes it easy to add any number of plugins easily.

 

Theme structure

The main files are:

• default.hbs - The main template file
• index.hbs - Used for the home page
• post.hbs - Used for individual posts
• page.hbs - Used for individual pages
• tag.hbs - Used for tag archives
• author.hbs - Used for author archives

One neat trick is that you can also create custom one-off templates just by adding the slug of a page to a template file. For example:

• page-about.hbs - Custom template for the /about/ page
• tag-news.hbs - Custom template for /tag/news/ archive
• author-jamie.hbs - Custom template for /author/jamie/ archive

 

Development guide

The Starter theme provides a first-class development experience out of the box.

 

Setup

To see realtime changes during development, symlink the Starter theme folder to the content/themes folder in your local Ghost install.

ln -s /path/to/starter /ghost/content/themes/starter

Restart Ghost and select the Starter theme from Settings.

From the theme's root directory, install the dependencies:

npm install

If Node isn't installed, follow the official Node installation guide.

 

Start development mode

From the Starter theme folder, start development mode:

npm run dev

Changes you make to your styles, scripts, and Handlebars files will show up automatically in the browser. CSS and Javascript will be compiled and output to the built folder.

Press ctrl + c in the terminal to exit development mode.

 

Build, zip, and test your theme

Compile your CSS and JavaScript assets for production with the following command:

npm run build

Create a zip archive:

npm run zip

Use gscan to test your theme for compatibility with Ghost:

npm run test

 

Copyright & License

Copyright (c) 2013-2023 Ghost Foundation - Released under the MIT license.

starter's Issues

Updating dependencies

We can easily update dependencies to their latest version:

$ ncu
Checking /package.json
[====================] 15/15 100%

 autoprefixer               9.4.10  →   9.6.1 
 gscan                      ^2.0.0  →  ^2.7.0 
 gulp                        4.0.0  →   4.0.2 
 gulp-zip                    4.2.0  →   5.0.0 
 postcss-color-function      4.0.1  →   4.1.0 
 postcss-custom-properties   8.0.9  →   9.0.2 

For latest autoprefixer, we might also want to change the package.json and add this line:

...
    "browserslist": [
        "last 2 versions"
    ]
...

Because autoprefixer doesnt like it as a parameter in the function call anymore.

Let'start

Is there a way to apply the frontend theme to admin editor?

I am inclined towards providing WYSIWYG kinda visual look & feel to my content editors. Therefore, for example, if they're managing the homepage, they would be getting exact idea about how the frontend is going to look like.

Is there any way, I can load the frontend assets such as styling, icons, themes, fonts etc to the Ghost CMS admin editor?

Why is this broken?

To install and use Ghost on MacOS, it is tuned (on my system anyway) to cry foul unless the install sees Node 14.15, so that is what I am running. But this Starter Theme install, it is looking for Node 10? or 12? What am I supposed to do with this?

I want to create my own theme using the starter, but apparently, I need to backtrack to the old Node? Is that current?

yarn
yarn install v1.22.10
[1/5] 🔍 Validating package.json...
warning [email protected]: The engine "ghost" appears to be invalid.
warning [email protected]: The engine "ghost-api" appears to be invalid.
[2/5] 🔍 Resolving packages...
[3/5] 🚚 Fetching packages...
error [email protected]: The engine "node" is incompatible with this module. Expected version "^10.13.0 || ^12.10.0". Got "14.15.3"
error Found incompatible module.

Incomplete Documentation on Local Development

The documentation needs to also describe how to symlink for local development.
Adding some markdown to explain how you can do live reload development would be great.

The following should be more than enough for any new comer.

# Setup your theme
git clone https://github.com/TryGhost/Starter my-theme
cd my-theme
yarn

# Now setup a local ghost instance
cd ..
mkdir ghost-dev
cd ghost-dev
ghost install local

# Link my theme to ghost dev instance
cd content/themes
ln -s ~/my-theme .

# Restart ghost and start developing
cd ../..
ghost restart

# Now head on over to http://localhost:2368/ghost/
# You should now be able to see your theme in the theme directory.

The engine "ghost" appears to be invalid

Getting these warnings during theme installation. First time using Ghost.
Is there anything wrong with how the starter theme is configured?

Steps to reproduce:

• Install the latest Ghost
• Copy the starter theme into the project
• Run yarn install

Bookmarks have stretched thumbnails in Safari

In other browsers:

In Safari:

Missing implementation in post.hbs

In post.hbs it has the following comment:

{{!-- There are two options for how we display the byline/author-info.
        If the post has more than one author, we load a specific template
        from includes/byline-multiple.hbs, otherwise, we just use the
        default byline. --}}

but it doesn't actually show any implementation for either byline types 🤔 it feels like there is something missing here but I'm not sure if I'm missing something

https://github.com/TryGhost/Starter/blob/master/post.hbs#L35

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Using npm packages for Renovate presets is now deprecated. Please migrate to repository-based presets instead.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency postcss to v8.4.31 [SECURITY]
• Update dependency @rollup/plugin-babel to v6.0.4
• Update dependency @rollup/plugin-commonjs to v25.0.7
• Update dependency @rollup/plugin-terser to v0.4.4
• Update dependency postcss-preset-env to v8.5.1
• Update babel monorepo to v7.24.4 (@babel/core, @babel/preset-env)
• Update dependency @rollup/plugin-node-resolve to v15.2.3
• Update dependency rollup to v3.29.4
• Update CSS preprocessors (major) (postcss-import, postcss-preset-env)
• Update actions/checkout action to v4
• Update dependency rollup to v4
• Lock file maintenance
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/deploy-theme.yml

• actions/checkout v3
• TryGhost/action-deploy-theme v1
• ubuntu 22.04

npm

package.json

• @babel/core ^7.21.0
• @babel/preset-env ^7.20.2
• @rollup/plugin-babel ^6.0.3
• @rollup/plugin-commonjs ^25.0.0
• @rollup/plugin-node-resolve ^15.0.1
• @rollup/plugin-terser ^0.4.0
• bestzip ^2.2.1
• postcss ^8.4.24
• postcss-import ^15.1.0
• postcss-preset-env ^8.0.1
• rollup ^3.18.0
• rollup-plugin-livereload ^2.0.5
• rollup-plugin-postcss ^4.0.2

---

• Check this box to trigger a request for Renovate to run again on this repository

Local Development of Theme

Howdy folks 👋

In the Development section of the readme it says that you can run:

$ yarn install
$ yarn dev

and editing the CSS will automatically update the assets. But is it possible to actually see what this is supposed to look like anywhere? I was half expecting a local server that would show the template while I was working on it 🤔 Also this starter theme doesn't have a demo URL like the other themes that were released in January.

build zip upload fail

I clone this git repo，then install the dependencies and upload the ghost-starter-theme. i got an error.
here are the admin upload api response

{
    "errors":[
        {
            "message":"Failed to read zip file",
            "context":"ghost-starter-theme.zip",
            "type":"ValidationError",
            "details":"EACCES: permission denied, mkdir '/tmp/f60b92fb-9429-4733-941b-ef3990669e67/assets/built/'",
            "property":null,
            "help":"Your zip file might be corrupted, try unzipping and zipping again.",
            "code":null,
            "id":"bea48a00-a3af-11ea-87b7-f503e87db928"
        }
    ]
}

Starter theme fails gscan

After creating a repository using the Starter template and going through the installation instructions, when finally running npm run test the following error is given:

Your theme has 1 error!

Errors

Important to fix, functionality may be degraded.

• Error: Not all page features are being used
  Affected Files: page.hbs

When testing with the browser gscan tool the following details are provided:

This error only applies to pages created with the Beta editor. Some page features used by Ghost via the {{@page}} global are not implemented in this theme. Find more information about the {{@page}} global here.

Affected files:
page.hbs: @page.show_title_and_feature_image is not used

Looking into the {{@page}} documentation, I found more details to resolve this issue in my install by incorporating this helper into page.hbs

{{#match @page.show_title_and_feature_image}}
...content...
{{/match}}

@page.show_title_and_feature_image - true (default) or false value from Ghost Editor
This toggle, only available for pages, lets users hide a page’s title and feature image to create pages that look radically different than posts (for example, full-width headers, CTAs, and landing pages).

This setting is only available when using the new Beta editor. However, since the @page.show_title_and_feature_image is always present and defaults to true, supporting this feature in your theme won’t break anything for anyone using the old editor.

Using the @page object is not backward-compatible with earlier versions of Ghost: once implemented the theme will only be compatible with Ghost 5.54.1 or later.

Is this a known issue? I just created a theme from the template today 10/31/23. When attempting to upload the theme without a fix the following error is given in the Ghost admin dashboard:

I'm happy to submit a PR for a fix, but wanted to raise this issue first.

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: The renovate configuration file contains some invalid settings
Message: Invalid configuration option: node

Error while executing yarn dev

Hey Team,

I have received following error while trying to run the dev server on my local machine.

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /beeper/index.js require() of ES modules is not supported. require() of /beeper/index.js from //gulpfile.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules. Instead rename index.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /node_modules/beeper/package.json.

Looks like the beeper module used in gulpfile is converted to esm module and the file is no longer able to require it.

Production deployment via GitHub Action inject Livereload.js

When the theme get deployed via the GitHub Action in the theme, the livereload.js is injected into the production environment (despite having the value "production" for the BUILD variable on GitHub Repository)

Fatal Errors Must-fix to activate theme

Affected files:
partials\subscribe-form.hbs: The partial icons/loader could not be found

Bookmark Card Does not Display Image

The bookmark card displays the image in the editor, but not when published. This can be observed in the official theme page here - https://starter.ghost.io/write/.

This is due to extra CSS being added with .kg-bookmark-container, .kg-bookmark-container:hover in content.css:225. Remove flex-wrap: wrap;

gscan for Ghost 5.0 raises error for signup page - no support for tiers

When running the latest gscan for Ghost 5.0 compatibility on the current version of the theme, it raises the error "Replace {{@price.monthly}} and {{@price.yearly}} with {{#get "tiers"}} and {{monthly_price}} or {{yearly_price}}". It looks like the members pages need to be updated for the new tiers feature, or removed (the only official theme that uses those pages is Pico).

How to add Tailwindcss to the Starter theme

          Hello @royalfig I am looking into using TailwindCSS for my custom Ghost theme. I came across [this](https://forum.ghost.org/t/a-guide-for-developing-ghost-themes-with-tailwindcss/35680) post on the Ghost Forum. However, it is for the Gulp "configuration". If you have any pointers/ideas on how to get TailwindCSS implemented with Rollup I would appreciate it (I did try [this](https://forum.ghost.org/t/a-guide-for-developing-ghost-themes-with-tailwindcss/35680) plugin but it doesn't seem to be working). Cheer!

Originally posted by @Isaac-Tait in #60 (comment)

Lighthouse accessibility error

It appears that Lighthouse is unable to properly analyze the Starter theme. The score for each segment is displayed, except for the "accessibility" part, where there appears to be an error (see screenshot). Other themes from Ghost don't appear to have this issue.

Any ideas how to solve this and what the problem is?