How to Connect Craft Docs App to Ghost

David Bressler -

Craft is my favorite writing app.

There are reasons related to writing, a conversation too long for this post. Though, I’d be remiss if I didn’t point out how awful both Microsoft Word and Google Docs have become.

There are also reasons related to how well written each app is for each platform supported. This is distinctly different than a popular competitor, Notion, whose apps are slow and feel poorly written (I can’t judge whether or not they are, but that’s how they feel when using them).

Craft has created Craft X, a platform for integrating different tools into your Craft Document workflow. Craft X extends Craft to suit your needs.

Craft X is currently in developer preview, but built into the release you’re already using. No need to download beta software. Just turn on extensions in Advanced Preferences (which can be found by clicking on your name/icon in the top left corner, selecting Preferences, then Advanced).

Integration Craft with Ghost

You need to download the Craft X extension for “publish to blogs”. Right now Ghost and Medium are supported, but it’s one extension ‘file’ to load after which you get support for both.

Head to the extension page and follow the instructions there to install the extension. Then come back here.

Configuring the Publish to Blogs extension for Ghost

To connect Ghost, you need an API Key and endpoint URL. Took me a few minutes to figure this out, so I thought I’d share.

The key thing is that you need to setup an integration in Ghost to retrieve the API Key (and endpoint URL).

In Ghost Admin, on the bottom of the sidebar, click on the gear icon to bring up the Settings Page (Look for the highlighted ‘1’ in the screenshot below).

In the Advanced section, tap Integrations (Look for the highlighted ‘2’ in the screenshot above). At the bottom of the Integrations Page, select the button that says “+ Add custom integration”.

You’re asked to name the integration, so I named mine Craft. Naming it takes you to the Configuration Page, where you can see the Admin API Key (which is what you need to configure the extension in Craft) and the API URL (screenshot below).

It’s a small, but nice touch, that when you hover over either the API Key or the API URL, a copy button will appear making it easy to copy the API Key, and then separately, the API URL.

Then, in Craft, tap the CraftX Button —> Export to Blog —> Publish to Ghost

Once you select “Publish to Ghost” the configuration fields are right there. Fill them in. If you have an open doc, hit Publish to Ghost. It just works.

Keeping in mind this is beta software, and there’s so much more I could imagine doing with this extension, this is “export” not “sync”. Meaning...

  1. If you want to change/delete the post, you need to do it in Ghost.

  2. If you Publish to Ghost again… It publishes a second post. The Post URL has a number appended after the first post is made. So the first Post URL is the title-of-the-doc, the second is title-of-the-doc2.

  3. You’re going to want to review the formatting, which makes the decision to post the document as “published”… meaning, you have to unpublish it so that people don’t see it before you are ready for them to see it, then review it for formatting, then republish it. Also, if you want to email it out, or add Email formatting, you’re going to do it now, in Ghost.

  4. When the document is moved to Ghost, it creates a post with a single block of content. This is disappointing as it's really nice to write in blocks. You can still add blocks of content around the Craft Block... this likely indicates how this integration is expected to be used. I suspect you'd think about a Craft Doc being a block, not a full Ghost post; though that makes the decision to put it in Ghost and make it "published" curious.

It’s really important to keep in mind that when you Publish to Ghost from Craft, it sets the doc as Published not Draft. This is one thing I’d like to see changed (and perhaps I can change myself as the plugin is open source), because no matter what happens, I’d like to see what the post looks like on Ghost before publishing publicly (and possibly emailing it to readers, which after all, is really what Ghost is about).

These limitations are not unusual for this sort of thing, especially while CraftX is in beta / developer preview.

Also, these extensions don’t appear to work in the mobile (iPad, iPhone, mobile browser) apps. They do seem to work in both MacOS and Mac Safari versions. This explains why this post was written quickly, I'm taking my first flight in almost two years first thing in the morning, and I'm not taking my laptop but did want to share this before I get back.

And, yes, of course this post was written in Craft.

I love Craft. You can try it for free here or read more about the available CraftX extensions here.