Hello! Relatively new to the platform and recently came to understand from staff and the forum (thank you!) that I may sometimes need to update my theme (Headline) manually when Ghost adds new features because I added some theme customizations.
I wanted to make sure I’m doing this right because I feel like I’ve possibly overcomplicated it… I have some custom coding related to comments (Cove) and displays related to reading time, timestamp, URL, etc. It’s 5-6 basic cosmetic things. But they go into different files and I don’t have a great roadmap for what all of them are now that I’ve already done the work.
Recently I wanted to use the version of Headline WITH search because for some reason mine did not have that. So I downloaded the theme again and then went through all 5-6 customizations I had just done — just so I could use native search. I think maybe I just could have added some kind of search / handlebars into my already custom version? - but I wasn’t sure and didn’t want to miss any other code changes in the update.
Now - Ghost has added comments. I’m on Ghost (Pro) – so I think I can just turn on comments from the settings menu and go from there…
But I guess I just wonder what I do next time there’s some improvement related to the Headline theme: (A) how do I learn about it? and (B) what would I do to take advantage of that AND keep my customizations, e.g. create some kind of very clear memo to myself about exactly where all the custom code goes so it’s easy to drop it in in the right places? Or would there usually be some kind of new Handlebars helper that I would just put in the right place?
Or is it only Ghost but not Headline that would be updated?
Not sure how best to approach this. Thanks for any input!
There are a lot of different approaches to this issue, and you’ll need to find the method that works best for you (I list 3 below). That being said, offloading changes to Code Injection or just keeping things in separate files when possible will always make your life easier.
For keeping up with changes, all Ghost official themes are open source, so you can see the changes on their GitHub pages. For Headline, you can see that the Readme file was the most recent update. Clicking on the ## commits will show the history of theme changes.
Methods for keeping up to date
Manual
Watch GitHub to see the changes and then manually copy those changes into your own theme. This is the most straightforward and often the simplest way of going about things. Themes usually change incrementally, so this method isn’t as tedious as one might expect.
Fork the official theme in GitHub
This is the most advanced technique and requires some fluency with GitHub. This site goes over the basic process: How to build on top of the Casper theme in Ghost
just wanted to chime in on @RyanF awesome answer. I stumbled upon this a while back:
Very helpful to automate theme customizations, big or small.
To ans your questions:
I too often go to the theme’s Github page to check for new releases versions/changes.
I add a readme file to remind myself which files have been changed, and a comment (e.g. #cust) at the beginning of the custom code so i can Ctrl + F which places have been modified.
Hey @RyanF, a quasi-related question if you don’t mind.
I see that in the comment below yours that Ghost’s GitHub Theme Deploy integration is mentioned, something that I should finally get off my butt and actually set up (now that I’m developing locally while using VS Code and GitHub Desktop in place of developing online while using… Brackets ). I also see that there’s two links mentioned in the linked-to-post:
Are those two essentially the same things, or two different things doing a similar action?
Otherwise, if they are essentially the same thing I see they’re suggesting to insert somewhat different code into files with different names. The former says the following code should be inserted into a new file called .github/workflows/main.yml:
You can see that in comparing the two, and in particular the first three lines (in the latter) under steps, two lines have been adjusted and one of them is new. Shall I take it that I should disregard the file name and code in the former and instead utilise the file name and code in the latter?
I think we just need to update the docs on the first page, but both should work just fine. This is a process that takes a little bit of work to set up, but it’s just pure magic after that
The name of the file isn’t important, you can call it whatever you want. Just copy in the yaml code from the second example. Create an integration in Ghost admin and then copy those secrets into your GitHub repo. (These steps are spelled out in more detail in the link: Deploy Ghost Theme · Actions · GitHub Marketplace · GitHub)
After that, anytime you push to your Ghost repo, your theme will be updated automatically! One thing I just started doing is running npm version patch before pushing to GitHub. This will update the patch version of your theme from 1.0.0 to 1.0.1, e.g. It makes it easier to see in Ghost Admin that your theme was indeed updated.
One suggestion though. Seeing how those docs need updating, perhaps you might want to make it clear that the GHOST_ADMIN_API_URL and GHOST_ADMIN_API_KEY portions in the yaml file shouldn’t be replaced with the actual API_URL and API_KEY from the Ghost Integration page, seeing how that’ll apparently, uh, screw things up.
I recently set up GitHub Theme Deploy on another theme and instance, but couldn’t see the changes active on the site. I thought things weren’t set up properly but then noticed that the theme had in fact uploaded from GitHub but didn’t get activated. Am I correct in surmising that when changing the version number the newly updated theme must be manually activated from within the admin?
). I also see that there’s two links mentioned in the linked-to-post: