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:
- Outline the changes coming in Ghost 2.0 (or 1.x if using the Koenig beta)
- 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 
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.
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.
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 
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 (
) then weâre equally interested to hear how it went
