“Koenig” is the codename of Ghost’s future editor. You may have first heard about it in our Ghost 1.0 announcement and now with Ghost 1.23.0 it’s finally ready to start testing
Why are we working on a new editor? The 1.0 post summed it up nicely:
Improving Ghost’s Markdown editor has always been high on our list of priorities, but for a long time we’ve wanted to do more. Modern publications aren’t just text based, they’re comprised of diverse, dynamic elements from photographs to videos, detailed charts and rich embeds. We wanted to build something entirely new which would support all of those use-cases, and be extensible for new types of content in the future.
That is just scratching the surface of our future plans for the editor but for now we’re focusing on the basics — a really nice editing experience that offers more flexibility than markdown alone whilst rendering your content closer to the final output.
To summarise the underlying concept of Koenig it’s best to think of it as having two types of content: rich-text and cards. Rich-text covers all text content such as headers, paragraphs, lists, and general formatting. Interspersed within rich-text will be what we call “cards”. Cards represent non-text content (images, embeds, dividers, etc) or containers for other formats such as Code, Markdown or HTML.
But! Don’t worry, Markdown isn’t completely going away. We know everyone is used to writing in Markdown (and many people really love it!) so we wanted to marry the best parts of Markdown and traditional WYSIWYG editors by utilising Markdown formatting as shortcuts to performing editor operations. It should be possible to utilise your Markdown muscle-memory to really streamline your writing experience, if something feels unnatural or broken around that please let us know!
So, on to the feature list . Please read through to get an idea for what you can do with Koenig. It’s a bit lengthy but Koenig is still in beta with no in-app help or docs so we wanted to showcase everything that’s possible.
If you’re itching to get started, skip to the end. We cover how to enable Koenig, how to add support to your theme, and how to report problems.
Much like other WYSIWYG editors, basic formatting operations can be performed through a toolbar. Select the text you want to format and click to apply the desired formatting - hopefully that’s all self-explanatory One thing to note is that if you’re using the keyboard to select text you won’t see the toolbar until you move the mouse, we want the UI to stay out of the way as much as possible.
Links can be created via the secondary link toolbar/url input. If you have a link in your content, hover over it to get a clickable version along with an edit button to get the url input back.
Many of the formats as well as a few others can also be applied via keyboard shortcuts:
- ⌘/Ctrl+B toggles strong
- ⌘/Ctrl+I toggles emphasis
- ⌘/Ctrl+U toggles underline
- ⌘/Ctrl+K toggles the link input
Shift+Enter inserts a soft-break or
Markdown editing / text expansions
We want Koenig to feel like a natural progression from markdown so you can use typical markdown markup to create sections, cards, and apply formatting.
The following section expansions only work when typed at the beginning of a blank paragraph and will trigger as soon as the trailing space is typed:
##, and so on can be used to create a new heading section or change the heading level of an existing heading section
>will create a blockquote section
*will create an unordered list section
1.will create an ordered list section
Formatting expansions will trigger as soon as the final character is typed, no trailing space needed:
_..._= italic formatting
**...**= bold formatting
[example](https://example.com/)= link creation
There are also two special formats that trigger in the same way as normal format expansions but are edited differently afterwards:
~~strike~~= strikethrough formatting
`test`= inline code formatting
The difference for these last two formats is how to edit. If you place the cursor at the end of the formatted text and press Backspace the markdown expansion will be undone so that you can add more text before completing the expansion again to re-apply the formatting.
Finally we have card expansions, triggered when written as the first thing in a blank paragraph:
```will create a code card
---will create a divider card
![alt text](http://example.com/image.png)will create an image card using the supplied
In Koenig it’s possible to add dynamic, extensible content blocks to your posts which go beyond simple text. We call these blocks “cards”. At the moment the following cards are available in Koenig:
Some cards such as the Markdown, HTML, and Code cards will have an “edit” mode and will be in this mode when first inserted, you can exit this mode by pressing Escape or clicking to place the cursor outside of the card. To get back to edit mode you can double-click on a card, or select it by moving the cursor with the keyboard and then pressing ⌘/Ctrl+Enter.
There is also a card insertion shortcut accessible by typing
/ at the beginning of a blank paragraph. You can continue typing to filter the list then press Enter to insert the card.
For those of you who really can’t imagine dropping Markdown completely, the default Markdown editor that was released with Ghost 1.0 is available as a card within Koenig.
All of your existing markdown posts are actually Koenig posts already, it’s just that they are made up of a single Markdown card. Open up one of you’re existing posts and you’ll see what we mean!
You can upload images using the Image card (surprise!). We also know how often image captions have been a requested feature in Ghost so we’re happy to say the image card has a built-in caption feature! And that’s not all, you can also choose from three image width options: normal, wide, and full-bleed.
See the “Required theme changes” section below to ensure your published posts respect the selected image width.
HTML cards let you to add custom HTML code to your posts in case you have specific HTML such as an image gallery or callout markup.
It’s useful at the moment if you want to embed YouTube videos, Twitter cards, or similar by using the service’s full “embed” sharing option and copy/pasting the HTML. We’ll be improving embed support with a standalone Embed card soon.
Do you have some text in markdown format that you wish you could format quickly in Koenig?
No problem! Any text that is pasted into Koenig is run through Ghost’s markdown parser so that Koenig can treat it the same as a rich-text paste meaning you’ll get nicely formatted headings and text, image cards, and so on all automatically created for you.
If you copy content from an external source such as a webpage or even google docs, pasting it into Koenig should preserve the formatting as much as possible. Headers and basic text formatting will be copied across and cards should be created automatically for any supported content such as images.
However, it’s an on-going process to iron out any kinks here. If you notice any problems when pasting content into Koenig, please let us know by replying to the topic including as much detail as possible about what you tried to copy and how it failed. If possible, reduce what it is you are copy/pasting so that you can help us pinpoint exactly what isn’t working.
- Unsplash integration - Select Unsplash images in image cards
- Image file pasting - Copy then paste image files into Koenig to automatically create image cards and upload your images
- Embed card - Easy embed of YouTube videos, Twitter cards, Facebook cards, any many many more just by pasting the respective url
How to test
First, ensure you’re on Ghost 1.23.0 or later.
If you installed via Ghost-CLI you can use the really quick
ghost update command. Ghost(pro) customers on 1.x have been upgraded to 1.23.0 already.
(As an aside, if you’re a Ghost(pro) customer and still on Ghost 0.x, follow the migration guide to get the latest hotness.)
Required theme changes
Theme’s CSS should be prepared for content that has been edited with Koenig, for a complete example check the Casper Koenig implementation.
- All existing posts created with the Ghost 1.0 markdown editor are rendered in a wrapper element with
.kg-card-markdownCSS class (no change here but this class will be deprecated in the future).
- All posts edited or saved with the Koenig editor enabled are wrapped in an element with
.kg-postclass instead of
- Koenig allows images to be rendered as “wide” or “full-width” as well as adding captions to images but your theme needs to support this for the styles to work in your published posts
- Add support for the
<figcaption>elements (see below)
- Add support for
The full HTML structure for rendered image cards is as follows:
<figure class="kg-image-card"> <img src="..." class="kg-image (kg-image-wide|kg-image-full)"> <figcaption>...</figcaption> </figure>
- Add support for
<iframe>s or other content embedded in a
<figure class="kg-embed-card"> <iframe width="480" height="270" src="https://www.youtube.com/embed/JXpyslBvAnQ?feature=oembed" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe> <figcaption>...</figcaption> </figure>
Enabling Koenig in labs
To enable the new editor check the checkbox for “Koenig editor” under Labs in your blog’s admin area.
Note: Posts that have been edited with Koenig will only be editable with Koenig, even if you disable Koenig via labs. The only exception to this is posts that contain a single markdown card and no rich-text, they will open in the default Ghost 1.x editor when the labs flag is disabled.
Koenig follows the same browser support plan as Ghost-Admin (latest 2 versions of major vendors) with the notable exception that IE11 will not be supported.
- IE - not supported
- Edge - not supported - latest version may work to some degree but is known to have issues
- Mobile browsers - not supported - they may work but it’s not been tested and is not currently a focus area for development
- Chrome 66/67
- Safari 11.0/11.1
- Firefox 60/61
The beta has only been tested extensively in Chrome 66/67, if you are using a browser that’s in the supported list and run into problems please report by following the instructions below.
First, thank you for testing out the beta! If you run into bugs, errors, or weird behaviour we definitely want to hear about it! If something doesn’t feel natural or easy to use we want to hear about that too.
Please do not open Github issues but rather reply to this topic so that we can avoid noise on Github. Here’s a quick checklist to run through when reporting anything:
- check the Release Candidate issue first to see if it’s a known problem or something that simply hasn’t been implemented yet
- check the dev tools console for errors — dev tools can be opened on most browsers by right-clicking the page and choosing “Inspect” or “Inspect element” — and ensure you include them in your post, screenshots are usually preferable to copy/paste
- include as many detailed reproduction steps as you can
- be sure to mention which browser, browser version, and operating system you are using
Please don’t reply here. We’re looking for feedback and bug reports on what’s already available. Any discussions which don’t centre around feedback on the current editor will be removed from the topic - it’s not personal, we have limited resources and therefore a strict feature set for the initial release, the only way for this discussion to be useful is if we’re able to keep it focused.