✨ Koenig Editor - Beta Release

“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 :tada:

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 :smile:. 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.

Feature overview

Formatting toolbar

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 :smile: 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 <br>

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
  • - or * 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:

  • *...* or _..._ = 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 alt and src attributes

Cards

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:

Plus%20Menu%20s

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.

Markdown 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!

Image card

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.

:exclamation: See the “Required theme changes” section below to ensure your published posts respect the selected image width.

HTML

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.

Other features

HTML pasting

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.

Rich-text pasting

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.

Coming soon

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

Content wrapper

  • All existing posts created with the Ghost 1.0 markdown editor are rendered in a wrapper element with .kg-card-markdown CSS 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-post class instead of .kg-card-markdown.

Image classes

  • 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 <figure> and <figcaption> elements (see below)
  • Add support for .kg-image-wide and .kg-image-full classes

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>

Embed classes

  • Add support for <iframe>s or other content embedded in a <figure> element
<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.

:warning: 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.


Browser support

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.

Unsupported:

  • 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

Supported:

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

Reporting issues

First, thank you for testing out the beta! :heart: 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

Requesting features

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.

16 Likes

FAQ

Why “Koenig”?

It’s named after Friedrich Koenig, arguably the most significant figure in the history of publishing tools. Until 1804 printing presses were cumbersome, inefficient, and broke down constantly. Koenig’s press, which added a fucking steam engine to the mix, was the first in history to make mass news distribution possible - which in turn helped spread literacy and shaped generations to come.

It wasn’t the most famous publishing tool of its time. But it was definitively the best.

That felt like a good metaphor for our own ambitions here :dancer:t2::printer:

I hate it, I want to keep the old editor

The old editor is a Markdown card inside the new editor - and has been that way for a full year! So, good news, nothing changes! You can keep using the Markdown editor and just ignore all the new features - no worries.

4 Likes

I’ve been using it on and off since development started, and I’ve really enjoyed it so far!

There are a couple things I’ve noticed which don’t seem to be in the RC tracker -

  1. Night shift needs a little bit of love, specifically for the hover / focus styles in areas like the settings gear and card selector. As I was writing this, I also noticed the formatting toolbar also needs some love.

  2. With headings, it feels like something went wrong when the #s goes away after adding a space - I think it might be better if the #s go away after the editor styles can come into play (which is after I add some visible text).

  3. It’s really difficult to remove the text expansion mode for the first card - No matter how many times you hit the backspace the last expansion remains. This isn’t an issue with any other cards since hitting backspace will delete the card.

  4. If the plus menu is active and you delete a card, it stays in place. In this case, it acts like the formatting toolbar, but hitting escape doesn’t hide it, which is characteristic of the formatting toolbar. Maybe I’m overthinking it :joy:

2 Likes

Thanks @vikaspotluri123, that’s really useful feedback! :smile:

Night shift needs a little bit of love

Definitely, I’ve added it to the RC issue list. Koenig is the first part of Ghost-Admin that is using our new Spirit CSS framework so it’s not tied in to Night Shift yet.

It’s really difficult to remove the text expansion mode for the first card

I could reproduce with heading and block quote formatting so I’ve added that to the RC list. Were there any others you ran into? (Workaround for now is to write something, select the text then toggle the formatting using the toolbar)

:white_check_mark: Fixed on master

If the plus menu is active and you delete a card, it stays in place.

Good point, I think cursor movement should be disabled when the (+) menu is open or it should close the menu similar to how clicking closes the menu when re-positioning the cursor. Added to the RC list.

1 Like

At the moment clicking outside of the active container (eg HTML container) doesn’t deselect the current one, you have to either select another container or hit ESC. Not sure if this is intended behaviour but it sure tripped me up for a bit! Selecting all the text in the current container seems to be a bit hit and miss as well and I somtimes end up selecting the whole post. I can’t come up with a repeatable scenario for this yet though sadly :frowning:

At the moment clicking outside of the active container (eg HTML container) doesn’t deselect the current one,

With the 1.23.0 beta clicking on text outside of the card would exit edit mode but clicking on other elements wouldn’t exit edit mode.

:white_check_mark: This has already been fixed on master, you can track issues here Koenig: Release Candidate version · Issue #9623 · TryGhost/Ghost · GitHub

Selecting all the text in the current container seems to be a bit hit and miss as well and I somtimes end up selecting the whole post.

That’s interesting. To be clear is this when selecting text inside a container card such as the HTML/Markdown card? Is it when drag-selecting, triple-clicking, or when using the Cmd+A shortcut?

Woo!

Looks like this could be PEBKAC. If I’m not selected on a current card I have to first select one (get a blue outline around it) then click again to start editing it. This holds true for HTML cards at least. I guess I wasn’t expecting this behaviour and was then mashing CMD+A and selecting everything. If I double click a card everything works fine.

Ghost(pro) rollout is complete, if you have a 1.x blog you should now be on 1.23.0 and able to test the beta :smile:

2 Likes

Is there a way to add footnotes/superscript in Koenig?

1 Like

When copying a markdown code or a code block using the Koenig editor, there are two copies? I don’t know where the problem is.
1

1 Like

I noticed this too.

Another thing: when erasing a character, the whole word is erased. I don’t really like it since I’m used to do ctrl + erase if needed.

1 Like

I like the Koenig editor quite a lot, but I got a bit confused on using the standard editor vs. the markdown editor in the sense that I do understand the standard editor (or block type if you want) is the default one, allowing you to add a markdown block if you want.

However, I would maybe create two defaults: the standard editor vs. the markdown editor as there is a lot of overlap in how the two blocks function and I would assume that users would either prefer doing it in one or the other way.

This also comes from the different interaction approach between the two types of blocks. For the standard block you only get the toolbar when you select a text so that you can act upon it (style, link, etc.) while the markdown block activates the toolbar when clicking on the block (yet options are very similar with style, link and additional functionalities like lists - which I would see in the standard block as well - and images, which seem redundant if you already have a separated image block).

Also, since the image gallery is a highly requested feature, maybe it makes sense to adjust the image block to allow for basic galleries as well (apologies for drawing similarities with how Gutenberg works).

In terms of interacting with block, I would assume that for now only the edit option is available at first click, but probably in the future other actions would be available (i.e. duplicate/copy, move position, etc.). There is also the option to enable editing at first click on the block, while also providing duplication and movement options (i.e. on the left side of the block vs. edit on the bottom side (or top side - also needs consistency, I think).

Oh also night shift needs an update for Koenig.

Also, the fact that sometime erasing a character erases the whole word seems to be a bug since it doesn’t happen everytime.

And the duplicate copy/paste bug happened to me with markdown and code.

Another thing, this doesn’t work for me on Chrome/W10:

screenshot_27-05-2018_18-44-06%20

Image Caption not aligning to centre when added using latest Koenig Editor in Chrome Browser. Issue Link

Steps to Reproduce
Add image with caption
Image caption not centred
Technical details:
Adding style in code injection solves the issue

<style>
    figcaption {
        display: block;
        text-align: center;
    }
</style>

The editor add paragraph into my list and cannot delete theses paragraph :

Right. “Container” cards such as Markdown, HTML, and Code cards have a “rendered” state and an “edit” state. The raw content is only available in the edit state so you would need to double-click, click then click the edit button, or select via keyboard then press Ctrl/Cmd+Enter to enter edit mode to get the content.

The rendered state of a container card is always covered by an overlay because we can’t control what is shown underneath. If for example you put YouTube video embed into an HTML card then exit the edit mode you’ll see the embedded video, if there was no overlay you’d lose the ability to select or double-click to edit because you would be interactive with the embedded video player.

1 Like

@AcceptableIce superscript is allowed (you can see this by copy/pasting content with superscript text) but there’s not currently a keyboard or markdown shortcut for it. I’ll add it to the issue list :smile:

We don’t currently have any plans for footnote support. Maybe you could create a topic on the Ideas board so we can judge how big the use-case is?

@lacat that’s definitely a bug, I’ve added it to the issue list, thanks for reporting!

@angristan that definitely shouldn’t be happening. Does this happen for you all the time?

@dsecareanu Koenig will be the default editor, the markdown card is there more as an escape valve for smaller bits of content in pure markdown and for backwards-compatibility with Ghost 0.x/1.x posts. It’s definitely not intended to be a case of choosing one editor or the other.

That said we will be exploring the idea of post templates in the future where you can configure a default set of text and cards to speed up creation of certain types of content. If you’re dead-set on only ever using a markdown card then it’s possible you could use the post template feature to make your default post template contain a single markdown card.

@dsecareanu basic gallery support (a few images within an image card to be displayed in a grid) may be added to the image card in the future but is very unlikely to land in version 1.0. It’s also not currently clear if support would be added to the existing image card or if a new gallery card would be added.

The eventual idea is that the editor can be extended with custom cards. So if you have a particular slideshow or large image gallery that you want on your blog then you could add a 3rd party gallery/slideshow card or implement your own card to add that support.

@angristan and anyone else reporting issues, please read the known issues list before posting so that we can avoid duplication here, thanks :smile:

@angristan did you check the DevTools console for any errors? If you’re reporting bugs please follow the instructions in the OP, it’s difficult if not impossible for us to diagnose things with just a “doesn’t work” message.

If you are using the default Casper theme then everything should be fine. If you’ve modified the theme in any way then you’ll need to update it by following the instructions in the opening post. Full changelog for Casper is here but you will need to adapt the changes to work with your theme.

@Roi_de_la_Poudre is this after pasting content into the editor? We’ll need more info about how you got into that state to be able offer any advice or determine if there’s a bug

2 Likes

@lacat what browser and browser version are you using? There are a number of CSS problems shown in your screen cap.

FYI, the two-copies bug is fixed on master ready for tomorrow’s patch release.

Just another quick idea, if not already covered someplace else:

  • maybe add a label for the code block as well (similar to html/markdown, as seen below)
  • I would say add a label for image block too, but that’s kind of obvious (as is the divider)

image