How to add a popup to Ghost
Ghost already includes Portal, a membership signup modal, and if members are your goal you should use it. A lead magnet, a survey, a sponsor waitlist or a pre-launch list for a second product is a different job, and that is where a PopupForge popup fits, installed through the Code Injection panel every Ghost site has.
Code Injection works the same on Ghost(Pro) and self-hosted installs, with no plan restriction. The one dependency is your theme: Ghost injects footer code through the ghost_foot helper, so a custom theme that omits it will silently drop the tag.
The script tag
<script src="https://getpopupforge.com/lead-modal.js?appId=YOUR_APP_ID&configId=YOUR_CONFIG_ID" async defer></script>Replace YOUR_APP_ID and YOUR_CONFIG_ID with the values from the install panel of your published popup. The tag is the same on every platform; only where you paste it changes.
Step by step
- 01
Build and publish the popup in PopupForge
Create a free account, generate or design the popup in the visual editor, set the trigger and frequency, then publish it. The install panel shows your script tag with the appId and configId already filled in. Copy that exact tag; the placeholder version on this page will not load a popup.
- 02
Open Settings > Code injection
In Ghost Admin click Settings (the gear at the bottom of the sidebar), scroll to the Advanced group, and open Code injection. You will see two editors: Site header and Site footer.
- 03
Paste the tag into Site footer
Paste the PopupForge script tag into Site footer and click Save. Ghost outputs footer injection before the closing body tag on every page rendered by your theme: home, posts, pages, tags and authors.
- 04
Optional: inject on a single post or page
Open the post in the editor, click the settings icon, scroll to Code injection, and paste the tag into Post footer. Useful for a lead magnet that belongs to one article; site-wide plus PopupForge URL targeting scales better.
- 05
Confirm your theme includes ghost_foot
Ghost themes must call the {{ghost_head}} and {{ghost_foot}} helpers in default.hbs. Official themes such as Casper and Source do. If you run a custom theme and the tag never appears in the page source, open default.hbs and check that {{ghost_foot}} sits before </body>.
- 06
Decide how the popup and Portal coexist
If Portal already opens on the same pages, delay the PopupForge trigger or limit it with URL targeting so members are not hit with two modals. A common split is Portal for subscriptions and PopupForge for a downloadable guide on specific tag pages.
- 07
Test the popup and check the lead arrives
Open the live site in a private browsing window so a previous session does not suppress the popup, trigger it the way you configured (wait for the delay, scroll, or move the pointer out through the top of the window), submit a test lead, then confirm it shows in the PopupForge lead list.
Ghost notes and gotchas
- Code injection saves and goes live immediately; there is no publish step.
- Ghost(Pro) serves pages through a CDN. If the tag does not appear right away, hard refresh or wait a minute before assuming it failed.
- Ghost's member-only content still renders the theme footer, so the popup can appear on gated posts. Exclude them with URL targeting if that is not what you want.
- The Ghost newsletter emails do not run scripts, so the popup only exists on the website, never inside emails.
Verify the install
Confirm the popup shows and the lead arrives
- 1.Open the publication in a private window and search the page source for lead-modal.js.
- 2.Trigger the popup on the home page and on a post, submit a test lead.
- 3.Confirm the lead in PopupForge and the analytics counts.
Official Ghost documentation
- Ghost tutorial: How to use Code Injection in Ghost
- Ghost theme docs: template structure (ghost_head and ghost_foot)
Platform menus and plan rules change. If a step here no longer matches what you see, the official page above is the source of truth.
FAQ
Frequently asked questions
Should I use PopupForge or Ghost Portal?
Portal for membership and newsletter signups, since it writes straight to Ghost members. PopupForge for everything Portal does not do: lead magnets, multi-step surveys, waitlists and offers delivered to CSV, email, Slack or a webhook.
Does this work on self-hosted Ghost?
Yes. Code injection is part of Ghost core, so Ghost(Pro) and self-hosted installs behave the same. The only requirement is a theme that outputs ghost_foot.
Why is the tag missing from my page source?
Almost always a custom theme without the {{ghost_foot}} helper in default.hbs, or a CDN that has not refreshed yet. Check the helper first, then hard refresh.
Header or footer injection?
Footer. It keeps the script out of the head, where Ghost already outputs meta tags and structured data, and the async and defer attributes mean load order does not matter.
Get your script tag
Generate a popup for your site, then paste one tag into Ghost.
The free generator shows three brand-matched directions from your URL, no account needed. Creating an account gives you the visual editor, triggers, URL targeting and the install panel with your real appId and configId.