> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weelkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ghost setup

> Connect a Ghost site with an Admin API key from a custom integration, and understand validation, updates, status and failure behavior.

The Ghost integration publishes posts and pages to a Ghost site through Ghost's Admin API, authenticated with an Admin API key from a custom integration you create in Ghost Admin.

## Connect a site

**1. Create a custom integration in Ghost**

In Ghost Admin, go to **Settings → Advanced → Integrations** and click **Add custom integration**. Name it something recognizable, such as `Weelkit`.

**2. Copy the Admin API key**

Copy the integration's **Admin API key**. It has the form `id:secret` — a hex id and a hex secret joined by a colon. Copy the whole value.

**3. Enter the site URL and key in Weelkit**

In Weelkit, open **Organization settings → CMS**, choose **Connect CMS**, and choose **Ghost**. Enter your **Site URL** and paste the **Admin API key**, then choose **Connect**.

**4. Weelkit validates the connection**

Weelkit checks the key's `id:secret` shape before sending anything, so a mis-pasted key fails straight away. Then it confirms the key can sign in to your site's Admin API, and shows your site's title.

**5. Map, set defaults and verify**

Choose posts or pages, review and save the field mapping, set the publishing defaults, and choose **Verify test draft**: the same flow as every schema-backed destination in the [publishing overview](https://docs.weelkit.com/integrations/overview.md#mode-a-schema-backed-destination).

## Discovered schema

Weelkit discovers **posts** and **pages** with these fields:

| Field | Notes |
| - | - |
| `title` | Post or page title |
| `html` | Body content as HTML |
| `custom_excerpt` | Excerpt |
| `slug` | URL slug |
| `feature_image` | Feature image |
| `feature_image_alt` | Feature image alternative text |
| `feature_image_caption` | Feature image caption |
| `meta_title` | Meta title |
| `meta_description` | SEO description |
| `canonical_url` | Canonical URL |
| `og_image`, `og_title`, `og_description` | Open Graph image, title and description |
| `twitter_image`, `twitter_title`, `twitter_description` | Social image, title and description |
| `featured` | Featured flag |
| `visibility` | Visibility value |
| `custom_template` | Theme template |
| `codeinjection_head`, `codeinjection_foot` | Header and footer code |
| `published_at` | Publish timestamp |
| `tags` | Explicit reference to Ghost tags |
| `authors` | Explicit reference to Ghost users |

Choose either **posts** or **pages** as the primary publishing type. Weelkit fetches tag and author options because those fields explicitly reference Ghost's tag and user resources. The unselected post/page type is not silently converted into a reference source.

Mapped values must meet the discovered field limits. Plain feature-image captions keep literal text; intentionally mapped HTML keeps its markup.

## Draft and publish

The publishing defaults' **Default status** decides whether the editor's button sends a **draft** or **publishes** immediately. Start with drafts (see [Testing integrations](https://docs.weelkit.com/integrations/testing-integrations.md)) and switch to publishing once a draft has been verified end to end.

The article body uses an HTML card to preserve its markup. Inline images keep their source URLs, so those URLs must stay available. The mapped feature image has a separate upload and field result.

## Updates to an existing post

When an article is sent again, the publishing default **When the article already exists** decides what happens: **Always update existing** updates the same Ghost post, **Always create a new item** creates another, and **Ask before updating** asks you to confirm. Choose **Update article** to update the existing post, or **Cancel** to leave it unchanged. See [Send to your CMS](https://docs.weelkit.com/articles/checks-and-publishing.md#send-to-your-cms).

An update sends the saved article version prepared for that request. Ghost's revision check prevents a concurrent edit from being silently overwritten. Review any conflict before sending again. Mapped tags and authors replace their previous selections rather than adding to them.

## Status and address

Weelkit keeps each article's status in step with its Ghost post. A **published** post makes the article **Published**. A **draft**, **scheduled** or email-only (**sent**) post makes it **Draft**, and so does a post deleted from Ghost. The post's public URL becomes the article's address once it's live. See [After you send](https://docs.weelkit.com/integrations/overview.md#after-you-send).

## Replace the key

If Ghost needs fresh authorization, choose **Reconnect** and enter the new **Admin API key** for the same site. Weelkit validates it before replacing the saved credentials; the connection's mapping and published links stay attached to that site.

To rotate a working key, regenerate it in Ghost Admin, then choose **Test connection** in Weelkit. When the old key is rejected, **Reconnect** becomes available. Delete an old custom integration only after the replacement works. **Disconnect** removes the saved setup and is not needed just to reauthorize the same site.

## When the Admin API is unavailable

If the Ghost Admin API can't be reached or returns an error, Weelkit shows the result. If Ghost may already have received the post, the outcome stays unconfirmed. Choose **Check original CMS send** in the editor before sending again; that check does not create another post.

> [!NOTE]
>
> Weelkit never exposes Ghost credentials or raw Ghost error bodies. Admin API keys are stored encrypted and never displayed after entry, and Ghost's error responses are summarized into Weelkit's own error categories rather than shown verbatim.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.