Ghost 2.0 Theme Compatibility - Help & Support

Ghost 2.0 is coming soon and it includes a new editor with some new features that will increase the control authors have over their images and pave the way for future expansion. More powerful image support and future-compatibility is great but it does come at the expense of requiring themes to adapt and support the relevant markup and styles.

This topic will serve two purposes:

  1. Outline the changes coming in Ghost 2.0 (or 1.x if using the Koenig beta)
  2. Serve as a central topic for getting help with theme updates.

Keeping 2.0 compatibility discussion in this topic should allow us to more easily identify and document pain points and common solutions :smile:

Now, onto the changes…

Ghost 2.x HTML Changes

<div class="kg-card-markdown">

In Ghost 1.x the {{content}} helper would always output HTML wrapped inside a <div> with the .kg-card-markdown class, eg:

<div class="kg-card-markdown">

In Ghost 2.0 there will be no wrapper element. Themes will need to provide their own if they need one.

The {{content}} helper will now output content elements at the top-level so the above example becomes:


<figure> and <figcaption>

The new editor has native image and embed cards with built-in caption support that uses the semantic <figure> and <figcaption> elements. Themes should ensure that they these elements are supported and that they are styled well.

Example image with caption:

<figure class="kg-image-card">
    <img src="" class="kg-image">
    <figcaption>An example image</figcaption>

Captions are optional so ensure that the following displays well too:

<figure class="kg-image-card">
    <img src="" class="kg-image">

Finally, embeds use the the <figure> and <figcaption> elements too but may contain an <iframe> or other content with associated scripts.

:point_up: For embedded videos it’s useful to test and make sure that any scripts your theme may use to resize iframes still work. Example HTML:

<figure class="kg-embed-card">
    <iframe width="480" height="270" src="" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
    <figcaption>An example YouTube embed</figcaption>

Image size options

Ghost 2.0’s editor allows authors to apply three different size options to their images - “normal”, “wide”, and “full width”.

These size options are achieved by adding kg-width-wide and kg-width-full classes to the <figure> elements in the HTML output.

Normal image:

<figure class="kg-image-card">
    <img src="" class="kg-image">

Wide image:

<figure class="kg-image-card kg-width-wide">
    <img src="" class="kg-image">

Full-width image:

<figure class="kg-image-card kg-width-full">
    <img src="" class="kg-image">

It is expected that your theme supports the three sizes in a way that is appropriate for your theme layout but still respects the intentions of the varying options, typically this would mean expanding the image widths so they are wider than the main content container.

If you are using flexbox for your post content layout this may be fairly straightforward. If you aren’t using flexbox there are some resources that might help:

Testing theme compatibility

After installing or upgrading to Ghost 1.25.0 you will find a draft post titled “Koenig Demo Post” has been added to your list of stories. You can use the preview feature on that post to see how your theme fares without needing to publish it or make it public.

As we get closer to Ghost 2.0 we will also be releasing an update to GScan that will add a check for the image width classes - if they are missing then the theme will fail to validate as Ghost 2.x compatible.

Example themes

  • Casper (Ghost’s default theme) has already been updated to support Koenig beta and Ghost 2.0. You can see the full diff of changes to get an idea of what may need changing in your own theme.

:blush: If you have an open source theme that has been updated for Koenig (1.25.0+ please) please let us know so that we can add it here for reference and to help others :raised_hands:

Getting help

If you’re having trouble or are confused about anything please reply here and let us know! We want to make sure the upgrade process goes smoothly so having good documentation and real-world examples will be key.

Likewise, if you’ve already updated your theme and everything went well, you struggled in places, or maybe you even found some nice techniques (:muscle:) then we’re equally interested to hear how it went :smile:


I have updated all three of my themes to be ready for Ghost 2.0, and the Koenig editor beta. It was fairly painless in all cases.

First, I did my paid theme, Laminim, because a customer had asked for it. I started by searching for and updating all styles that relied on the existence of .kg-card-markdown, but left fallbacks for Ghost 1.x for the time being. Next, I did some research on robust ways to handle full-bleed images, and settled on a variation of the CSS-tricks version. Finally, I updated my general figure, figcaption, and .kg-embed-card styles so that videos and tweets looked good.

I did pretty much the same things with my open-source theme MNML, except that it uses plain ‘ol CSS rather than Sass. You can see a diff of what I did at:

Undefined, my open-source starter theme, only had five selectors in the stylesheet: the idea is that people bring their own CSS framework-of-choice. So I checked to make sure everything looked OK, and added some default styling for figures and figcaptions and starting points for styling the new image sizes. I left the full-bleed image stuff commented out so that people building on the theme would be free to take a different tack if they chose. You can see the diff of that at:

The only issue that I ran into is that the full-bleed images occasionally create a horizontal scrollbar. I spent a while trying to figure out what exactly was going on, and find an elegant fix. The solution people seem to be using is body {overflow-x: hidden;}. It feels like a hack, but it works, so I used it too. If Chris Coyier can tolerate it, it’s good enough for me :slight_smile:

Hope this helps!


@Kevin — Also, is there any way to get an RSS feed or some such of the themes changelog? I would be handy if there was a way of being notified when there is a change that might break themes without having to manually check that page, or hear about it from people using my themes…

1 Like

That’s great. :+1:

1 Like

@curiositry that’s great, thanks for sharing! :heart:

There’s no specific feed for the themes changelog. The closest thing is probably Ghost’s releases feed on Github, if there are any theme changes in a release then they will always be called out in the release notes.

1 Like

I have already implemented the Koening beta features like image cards and embed cards. To style {{content}} I didn’t used .kg-card-markdown css class to style content I used an extra wrapper for the content. In that way I think the removal of .kg-card-markdown will not effect the content layout.

But sometime I confused with theme with sidebar layout. What should be the the correct way to wide and full width image in such kind of theme layout. For example here is a theme live preview

It’s an interesting question but I think the answer will be very dependent on each particular theme’s layout. It could be that a theme doesn’t have true full-width images but has three variations in image size that make sense for the layout in question.

FYI, the example link you posted is not working for me at the moment, I get a server not found error.

Thanks for the reply. Fixed the link.

I had previously downloaded the default Casper theme, made some changes to HBS files, and uploaded that customized theme. (CSS was customized using code injection within admin UI). When I preview the demo post, the “wide” images do not really show as wide. I am thinking it is because the preview is not using the Ghost 2.0 theme but my old customized Casper theme (is that correct?).

What is the best way to upgrade to Ghost 2.0 so that I can preserve my HBS customizations?

I am thinking:

Option 1: perform the Ghost 2.0 upgrade through the my.ghost account settings UI. This will likely remove all my HBS changes (will it?). Then download the new Casper theme from the admin UI, and manually make all the HBS changes to it again.

Downside is that the hosted blog will look inconsistent for all the time it takes me to manually update the HBS files.

Option 2: Download the new Ghost Casper theme (from where?). Change it and upload it. Then, quickly perform the upgrade in the my.ghost account UI.

perform the Ghost 2.0 upgrade through the my.ghost account settings UI. This will likely remove all my HBS changes (will it?)

No, nothing will be changed automatically. If your current theme is not compatible you will be given instructions for how to make it compatible and an option to retry the upgrade. If your current theme is already compatible with Ghost 2.0 then the upgrade will happen and your current theme will be kept.

Download the new Ghost Casper theme (from where?)

Latest version of Casper is always available at Releases · TryGhost/Casper · GitHub

Then, quickly perform the upgrade in the my.ghost account UI.

The changes that you need to make can be backwards-compatible. It’s possible to run your Ghost 2.0 compatible theme on Ghost 1.x with no visual issues and upgrade at your convenience.

Thanks. I tried the first option and was shown the theme compatibility errors - very helpful. But does assume expertise in creating theme CSS for missing classes.

(Suggestion: I would have been less nervous about clicking the “Upgrade” button if it was clearer that this will not immediately start the upgrade and possibly leave the blog in an error/ugly state. Maybe the button could be called “check compatibility.” And after that it can say Proceed to upgrade or something.)

Is it possible to migrate from Wordpress to Ghost? If yes then what’s the way forward?

Surendra Dhote
Editor @ Proche

Yes, it’s possible, the path being (as far as I remember, please correct me if wrong):

Some more info here:

@Kevin it would be great to replace this pinned post with one that references Ghost version 3! This one (referencing version 2) is outdated since Ghost v3.

As it is a pinned post, it does no justice to new visitors, and on first glance it makes the whole forum appear outdated. IMHO.

1 Like

I don’t seem to be able to edit my original post, but all the themes mentioned in it have been updated to support Ghost 3.0, and Undefined and Weblog have full paid membership support out-of-the-box.