Ghost 2.0 Theme Compatibility - Help & Support


#1

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">
    <p>...</p>
    <p>...</p>
    <p>...</p>
</div>

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:

<p>...</p>
<p>...</p>
<p>...</p>

<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="https://example.com/image.jpeg" class="kg-image">
    <figcaption>An example image</figcaption>
</figure>

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

<figure class="kg-image-card">
    <img src="https://example.com/image.jpeg" class="kg-image">
</figure>

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="https://www.youtube.com/embed/CfeQTuGyiqU?feature=oembed" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
    <figcaption>An example YouTube embed</figcaption>
</figure>

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="https://example.com/image.jpeg" class="kg-image">
</figure>

Wide image:

<figure class="kg-image-card kg-width-wide">
    <img src="https://example.com/image.jpeg" class="kg-image">
</figure>

Full-width image:

<figure class="kg-image-card kg-width-full">
    <img src="https://example.com/image.jpeg" class="kg-image">
</figure>

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:


✨ Koenig Editor - Beta Release
Create a post makdown language
#2

#3

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!


#4

@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…


#5

That’s great. :+1:


#6

@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.


#7

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


#8

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.


#9

Thanks for the reply. Fixed the link.