Skip to main content

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.

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 content recommendation modules at the same time.
If you’re using the 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.
The full starter kit with all files is available on GitHub: 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). This embed key is the per-blog 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.
  • A Contextly for Ghost account (optional, for content recommendations)

​
Integration files

The starter kit provides a partials/integrations folder with these files:
FilePurpose
outpost.hbsLoads the Outpost script on every page
outpost-api-key.hbsStores your Outpost embed API key (the per-blog public key, distinct from the Integration API key)
outpost-domain-name.hbsStores your Outpost domain name
contextly.hbsLoads the Contextly script (optional)
contextly-module.hbsRenders the Contextly recommendation widget in posts (optional)
contact-form.hbsRenders an Outpost contact form (optional)

​
Setup instructions

Choose the method that matches how you manage your theme:

​
Step 1: Download the files

Download the Outpost 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:
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 → 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 example 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}}:
{{> integrations/outpost}}
{{> integrations/contextly}}
If you are not using Contextly, omit the {{> integrations/contextly}} line.

​
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:
{{> integrations/contextly-module}}
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}}.

​
Step 7: Upload to Ghost

Zip your theme folder, then upload it in Ghost Admin → Settings → Design → Change theme → Upload.

​
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
If you added your Contextly API key to Outpost (under Integrations → Contextly), you can log into Contextly directly from Outpost.

​
Troubleshooting

  • 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
  • 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
Edit the embed API key and domain name files locally rather than through GitHub’s web editor, which sometimes adds trailing newlines.

Theme Connect Wizard

Let Outpost update your theme automatically instead of editing files manually.

Integration Kit on GitHub

Download the starter kit with all integration partial files.

Contact Support

Contact the Outpost team for help with theme integration.