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

# Theme Connect Wizard

> Upload Ghost themes, switch between them, and integrate Outpost features like CTAs, gift subscriptions, tip jar, and events — with a managed GitHub repo for every theme you upload.

The Theme Connect Wizard connects your Ghost theme to Outpost. Upload a theme; the wizard modifies it to enable in-post CTAs, gift subscriptions, tip jar, events, and Contextly recommendations, then deploys it to your Ghost site through a managed GitHub repository. You can keep multiple themes side by side and switch the active one whenever you want.

<Info>
  Find the wizard under **Labs → Theme Connect Wizard** in your dashboard. It also runs as part of the **Voyager and Luna onboarding flow** — when you sign up for those plans, you'll upload your theme through the wizard during setup, and you can return to it anytime to upload a new theme, switch themes, or manage GitHub access.
</Info>

***

## When to run the wizard

Open **Labs → Theme Connect Wizard** any time one of these happens:

* **You changed your Ghost theme.** A new theme replaces the connected one, so the Outpost integration code is no longer present. Re-run the wizard with the new theme to restore in-post CTAs, tip jar, gift subscriptions, and events.
* **You updated your existing theme** (installed a new version from the developer, edited templates, etc.) and Outpost features have stopped working — popups not appearing, CTAs not rendering, tip jar missing. A theme update can overwrite the integration files; uploading the updated theme through the wizard reapplies them.
* **The wizard's connection banner says your theme isn't connected.** That's the wizard telling you the active Ghost theme is missing the integration. Upload the current theme to fix it.
* **You want to switch back to a previous theme.** Use the **Themes** table to activate any processed theme — no re-upload needed.

If you're unsure why something isn't rendering, click **Check** on the wizard first. It tells you whether your active theme is actually connected to Outpost.

<Frame>
  <img src="https://mintcdn.com/outpost-eb0cfbad/R5BAj0iC-vkIGsTu/images/Check-button-on-theme-connect-wizard.png?fit=max&auto=format&n=R5BAj0iC-vkIGsTu&q=85&s=50e16f5d71a21d80fd05c8043876d837" alt="Check Button On Theme Connect Wizard" width="278" height="132" data-path="images/Check-button-on-theme-connect-wizard.png" />
</Frame>

***

## Connection status

The banner at the top of the page tells you whether your active Ghost theme is connected to Outpost:

* **"Your current theme is connected to Outpost"** (green) — your active Ghost theme includes the integration code; in-post CTAs, gift subscriptions, and tip jar will render correctly.
* **"Your current theme is not connected to Outpost"** (red) — your active theme doesn't have the integration, or the integration is outdated.

Click **Check** to re-verify the connection at any time. If you've just changed themes inside Ghost, run a check here to confirm the new theme is integrated.

***

## Multiple themes and switching

Every theme you've uploaded appears in the **Themes** table. You can keep as many processed themes as you want and swap the active one without re-uploading.

| Column              | Description                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Date**            | When the theme was processed.                                                                                      |
| **Name**            | The theme name.                                                                                                    |
| **Manifest Status** | Whether the theme's manifest is **Valid**, has warnings, or is **Not present**, with a refresh button to re-check. |
| **Action**          | **Activate** to switch to this theme, or an **Active** badge marks the currently deployed one.                     |

Click any row to expand it and reveal the GitHub repo details and a **Manifest** button. Manifest warnings or errors open in a separate dialog — most are non-blocking.

Activating a theme deploys it to your Ghost site and makes it the live theme — no need to touch Ghost's theme settings.

<Tip>
  Keep your previous theme around as a fallback. If a new theme misbehaves, you can revert to the old one with a single click.
</Tip>

***

## Uploading a theme

<Steps>
  <Step title="Upload your theme">
    Upload your Ghost theme as a .zip file (max 15 MB). This is the same file you'd download from Ghost under Settings → Theme.
  </Step>

  <Step title="Outpost processes the theme">
    The wizard analyzes your theme to auto-detect its content structure, then updates the theme files to enable Outpost features.
  </Step>

  <Step title="Deployment via GitHub">
    Outpost commits the modified theme to its managed GitHub repo for your site, then pushes it to your Ghost site automatically.
  </Step>

  <Step title="Theme activation">
    The updated theme is set as your active Ghost theme. The process works automatically for most themes.
  </Step>
</Steps>

### Processing progress

After clicking **Continue**, the wizard shows a progress bar with these steps:

1. **Upload theme** — Sends the .zip to Outpost
2. **Adding Outpost integration** — Updates the theme to enable Outpost features
3. **Integrating Contextly** — Adds AI recommendation support (Luna plan only)
4. **Connecting your modified theme to GitHub** — Stages the updated theme for delivery
5. **Deploying to Ghost** — Pushes the theme to your Ghost site
6. **Activating theme** — Sets the deployed theme as active in Ghost

***

## What gets integrated

When the wizard processes a theme, it enables:

* **In-post CTAs** — Conversion widgets within post content
* **Gift subscriptions** — Gift purchase and redemption flows
* **Tip jar** — Donation widgets on your site
* **Events** — Registration widgets for webinars and events
* **Contextly recommendations** — AI-powered content recommendations (Luna plan)

### Content selector auto-detection

Different Ghost themes use different HTML structures to wrap post content. The wizard auto-detects the right selector — including non-standard ones from custom or third-party themes — so in-post CTAs inject in the correct location. If auto-detection picks the wrong target, you can override it in CTA Default Design settings.

***

## GitHub repo and collaborators

Every theme you upload lives in a GitHub repository that Outpost manages on your behalf. The repo is what makes deployments to your Ghost site fast and rollbackable, and it's also the place where developers on your team can work directly on theme files if they want to.

### Viewing your repo

The repo details appear as an advanced setting on each theme, once a theme has been pushed to GitHub. Open the theme's row to reveal:

* The GitHub repository URL
* HTTPS and SSH clone commands
* The latest commit SHA, author, and message

This is useful if you want to clone the repo locally to make custom edits or audit what the wizard changed.

### Adding collaborators

You can invite GitHub users to collaborate on your theme repository directly from the wizard:

1. Open the theme's GitHub details section
2. In the **Add Collaborator** form, enter a GitHub username and click **Invite**
3. The invite appears under **Pending Invitations** until the user accepts
4. Once accepted, they show up under **Current Collaborators** with their username, avatar, and permission level

Use **Remove** to revoke access for an active collaborator, or **Revoke** to cancel a pending invite.

<Tip>
  Adding a developer as a collaborator lets them push theme changes through the standard Git workflow. The wizard still handles the deploy-to-Ghost step on every push.
</Tip>

***

## Manual fallback

If automatic deployment fails, the wizard provides a manual path:

1. **Download** the modified theme using the button shown
2. Go to **Ghost → Settings → Theme**
3. Upload the downloaded theme .zip file
4. Activate the theme in Ghost

If you hit issues, contact [support@outpost.pub](mailto:support@outpost.pub).

***

## Related features

<CardGroup cols={2}>
  <Card title="CTAs" icon="bullhorn" href="/features/ctas">
    The in-post CTAs enabled by theme integration.
  </Card>

  <Card title="Events" icon="calendar" href="/features/events">
    Event registration widgets that require theme integration.
  </Card>

  <Card title="Tip Jar" icon="hand-holding-dollar" href="/features/tip-jar">
    Donation features enabled by theme integration.
  </Card>

  <Card title="Gift Subscriptions" icon="gift" href="/features/gift-subscriptions">
    Gift purchase flows enabled by theme integration.
  </Card>
</CardGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to re-run the wizard after updating my Ghost theme?">
    Yes. If you update your theme outside Outpost (e.g., installing a new version from the theme developer), upload the new version through the wizard so the Outpost integration is reapplied. Existing themes stay in your themes list — you can revert to one of them at any time.
  </Accordion>

  <Accordion title="Can I keep multiple themes processed at once?">
    Yes. Every theme you upload stays in your Themes table. Use **Activate** to switch — the previous theme remains in the list as an instant fallback.
  </Accordion>

  <Accordion title="Where does the wizard live in the admin?">
    Open it from **Labs → Theme Connect Wizard** in your dashboard sidebar. Voyager and Luna publishers also run it as part of their onboarding flow.
  </Accordion>

  <Accordion title="Does the wizard modify my original theme files?">
    The wizard creates a modified copy of your theme inside its managed GitHub repo. Your original .zip file is not changed — the modified version is what gets deployed to Ghost.
  </Accordion>

  <Accordion title="What if the wizard doesn't support my theme?">
    The wizard works with most Ghost themes. If you hit an error, try the manual fallback. For persistent issues, contact [support@outpost.pub](mailto:support@outpost.pub).
  </Accordion>

  <Accordion title="Why does the wizard need GitHub?">
    GitHub is how Outpost stores and deploys your theme. Every change is committed to a managed repo, which gives you version history, an instant audit trail, and a clean way to add developer collaborators who can edit the theme directly.
  </Accordion>

  <Accordion title="Can my developer push changes directly to the theme repo?">
    Yes. Add them as a collaborator from the wizard's GitHub details section. Once they accept the invite, they can clone the repo and push changes through the standard Git workflow — the wizard handles deployment to Ghost on every push.
  </Accordion>
</AccordionGroup>