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

# Ghost Theme Integration

> How to manually update your Ghost theme to work with Outpost and optionally Contextly recommendations.

This guide walks you through adding the Outpost integration files to your Ghost theme. Once complete, your theme will load the Outpost script on every page, enabling CTAs, paywalls, member tracking, and other Outpost features.

Optionally, you can also add [Contextly](https://contextly.com) content recommendation modules at the same time.

<Info>
  If you're using the [Theme Connect Wizard](/getting-started/theme-connect-wizard) in Outpost, these steps are handled automatically. This guide is for publishers who prefer to update their theme manually or need to troubleshoot a custom integration.
</Info>

The full starter kit with all files is available on GitHub: [Outpost-Contextly-Theme-Integration-Kit](https://github.com/OutpostPublications/Outpost-Contextly-Theme-Integration-Kit).

***

## Prerequisites

* An active Outpost account on the Voyager or Luna plan
* Access to your Ghost theme files (via GitHub or download/upload)
* Your **Outpost embed API key** and **Outpost domain name** (found in **Account > Core Connections** in the [Outpost admin](https://admin.outpost.pub)). This embed key is the per-site public key the theme uses to load the Outpost script — it is **not** the same as the Integration API key used by the [Integration API](/api-reference/introduction).
* A [Contextly for Ghost](https://ghost.contextly.com/login) account (optional, for content recommendations)

***

## Integration files

The starter kit provides a `partials/integrations` folder with these files:

| File                      | Purpose                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `outpost.hbs`             | Loads the Outpost script on every page                                                             |
| `outpost-api-key.hbs`     | Stores your Outpost embed API key (the per-site public key, distinct from the Integration API key) |
| `outpost-domain-name.hbs` | Stores your Outpost domain name                                                                    |
| `contextly.hbs`           | Loads the Contextly script (optional)                                                              |
| `contextly-module.hbs`    | Renders the Contextly recommendation widget in posts (optional)                                    |
| `contact-form.hbs`        | Renders an Outpost contact form (optional)                                                         |

***

## Setup instructions

Choose the method that matches how you manage your theme:

<Tabs>
  <Tab title="Download / Upload">
    ### Step 1: Download the files

    Download the [Outpost Theme Integration Kit](https://github.com/OutpostPublications/Outpost-Contextly-Theme-Integration-Kit) from GitHub and unzip it.

    Download your current theme from Ghost and unzip it. We recommend keeping a backup copy of the original.

    ### Step 2: Copy the integration partials

    Copy the `partials/integrations` folder from the starter kit into the `partials` folder of your theme.

    Your theme's file structure should look like:

    ```text Theme directory layout theme={"theme":{"light":"github-light","dark":"github-dark"}}
    your-theme/
    ├── default.hbs
    ├── post.hbs
    ├── partials/
    │   ├── integrations/
    │   │   ├── outpost.hbs
    │   │   ├── outpost-api-key.hbs
    │   │   ├── outpost-domain-name.hbs
    │   │   ├── contextly.hbs
    │   │   ├── contextly-module.hbs
    │   │   └── contact-form.hbs
    │   └── ... (your existing partials)
    └── ...
    ```

    ### Step 3: Add your Outpost API key

    1. Open `partials/integrations/outpost-api-key.hbs` in a text editor
    2. Go to your [Outpost admin](https://admin.outpost.pub) → **Account** → **Core Connections**
    3. Copy your **Outpost embed API key**
    4. Replace `Sample_Outpost_API_Key` with your key
    5. Make sure there are no extra lines or spaces in the file
    6. Save

    ### Step 4: Add your Outpost domain name

    1. Open `partials/integrations/outpost-domain-name.hbs` in a text editor
    2. From the same Core Connections page, copy your **Outpost Domain Name**
    3. Replace the `Sample_Outpost_Domain_Url` placeholder with your domain name
    4. Make sure there are no extra lines or spaces in the file
    5. Save

    ### Step 5: Add the Outpost script to default.hbs

    Open your theme's `default.hbs` file and add the following code directly below `{{ghost_foot}}`:

    ```handlebars default.hbs theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {{> integrations/outpost}}
    {{> integrations/contextly}}
    ```

    <Note>
      If you are not using Contextly, omit the `{{> integrations/contextly}}` line.
    </Note>

    ### Step 6: Add Contextly recommendations to posts (optional)

    To display the Contextly recommendation widget at the end of your posts, open `post.hbs` (or your theme's post template) and add the following code after the `{{content}}` section, before comments or the author bio:

    ```handlebars post.hbs theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {{> integrations/contextly-module}}
    ```

    <Tip>
      If your theme has multiple post templates (e.g., `custom-post-*.hbs`), add this code to each template where you want recommendations.

      Alternatively, if your theme has a `partials/related.hbs` partial for related content, you can replace its contents with `{{> integrations/contextly-module}}`.
    </Tip>

    ### Step 7: Upload to Ghost

    Zip your theme folder, then upload it in **Ghost Admin → Settings → Design → Change theme → Upload**.
  </Tab>

  <Tab title="GitHub">
    ### Step 1: Get the integration files

    Download the [Outpost Theme Integration Kit](https://github.com/OutpostPublications/Outpost-Contextly-Theme-Integration-Kit) and unzip it.

    ### Step 2: Add partials to your repo

    Copy the `partials/integrations` folder into your theme's `partials` directory.

    ### Step 3: Add your Outpost API key

    1. Open `partials/integrations/outpost-api-key.hbs` in a **local** text editor (the GitHub web editor sometimes adds unwanted whitespace)
    2. Go to your [Outpost admin](https://admin.outpost.pub) → **Account** → **Core Connections**
    3. Copy your **Outpost embed API key**
    4. Replace `Sample_Outpost_API_Key` with your key
    5. Make sure there are no extra lines or spaces — save

    ### Step 4: Add your Outpost domain name

    1. Open `partials/integrations/outpost-domain-name.hbs` locally
    2. Copy your **Outpost Domain Name** from Core Connections
    3. Replace the `Sample_Outpost_Domain_Url` placeholder with your domain name — save

    ### Step 5: Add the Outpost script to default.hbs

    Add the following code directly below `{{ghost_foot}}` in `default.hbs`:

    ```handlebars default.hbs theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {{> integrations/outpost}}
    {{> integrations/contextly}}
    ```

    Omit the Contextly line if you're not using it.

    ### Step 6: Add Contextly recommendations to posts (optional)

    In your `post.hbs` (or each custom post template), add after `{{content}}`:

    ```handlebars post.hbs theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {{> integrations/contextly-module}}
    ```

    ### Step 7: Commit and deploy

    Commit your changes, open a pull request, and merge. If you use GitHub Actions to deploy your theme, check the Actions tab to confirm Ghost accepted the update. If not using Actions, download the theme as a zip and upload it to Ghost manually.
  </Tab>
</Tabs>

***

## Verifying the integration

After activating the updated theme:

1. Visit a post on your site and view the page source — you should see the Outpost script loading
2. Outpost features like CTAs, paywalls, and member tracking should begin working immediately
3. If using Contextly, recommendations should appear within 10 minutes. If they don't, log into Contextly → **Recommendations** → **Refresh All**

<Tip>
  If you added your Contextly API key to Outpost (under **Integrations → Contextly**), you can log into Contextly directly from Outpost.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Outpost features aren't loading">
    * Verify your embed API key in `outpost-api-key.hbs` has no extra spaces or newlines
    * Confirm the `{{> integrations/outpost}}` partial is included in `default.hbs` after `{{ghost_foot}}`
    * Check your browser's developer console for JavaScript errors
  </Accordion>

  <Accordion title="Contextly recommendations don't appear">
    * Wait 10 minutes after activating the theme
    * Log into Contextly and go to **Recommendations → Refresh All**
    * Verify the `{{> integrations/contextly-module}}` partial is placed after `{{content}}` in your post template
  </Accordion>

  <Accordion title="GitHub web editor adds unwanted whitespace">
    Edit the embed API key and domain name files locally rather than through GitHub's web editor, which sometimes adds trailing newlines.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Theme Connect Wizard" icon="wand-magic-sparkles" href="/getting-started/theme-connect-wizard">
    Let Outpost update your theme automatically instead of editing files manually.
  </Card>

  <Card title="Integration Kit on GitHub" icon="github" href="https://github.com/OutpostPublications/Outpost-Contextly-Theme-Integration-Kit">
    Download the starter kit with all integration partial files.
  </Card>

  <Card title="Contact Support" icon="envelope" href="https://outpost.pub/contact">
    Contact the Outpost team for help with theme integration.
  </Card>
</CardGroup>