# Project pack: Ghost @ db90cf0

Facts about **Ghost** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Ghost gives you a good-looking website with a blog and an email newsletter in one place. Write in a clean editor, publish to your site and send the same post to your subscribers by email. Readers can sign up for free, or pay a monthly fee for members-only posts, with payments handled by Stripe. It is used by independent writers, small businesses, clubs and local news sites, and you can run it on your own server.

## Version and source
- Repository: https://github.com/TryGhost/Ghost
- Pinned commit: `db90cf0f34cc09b88e3ea17ab2aa9fb5997467ec`. Use exactly this version.
- Get it: `git clone https://github.com/TryGhost/Ghost ghost && cd ghost && git checkout db90cf0f34cc09b88e3ea17ab2aa9fb5997467ec`
- Or download a zip: https://github.com/TryGhost/Ghost/archive/db90cf0f34cc09b88e3ea17ab2aa9fb5997467ec.zip
- Official docs: https://docs.ghost.org
- Licence: **MIT**. Free to use, change and share for any purpose, including commercial use. Keep the copyright and licence notice if you share the code. "Ghost" and the Ghost logo are trademarks, so don't present a changed copy as the official Ghost.

## Running it
- Easiest:

  ```sh
  # Official Docker set-up (docs.ghost.org/install/docker):
  git clone https://github.com/TryGhost/ghost-docker.git ghost && cd ghost
  cp .env.example .env && cp caddy/Caddyfile.example caddy/Caddyfile
  # edit .env: DOMAIN, DATABASE_ROOT_PASSWORD, DATABASE_PASSWORD and the mail__ settings
  docker compose up -d
  # then open https://your-domain/ghost to create the owner account.
  # To try it on your own computer instead: npm install ghost-cli -g && ghost install local  (http://localhost:2368)
  ```

- Needs: A server with Docker and Docker Compose and a domain name pointing to it, or Node.js 22 for Ghost-CLI, For theme work, only a text editor and a zip tool, For core development, Node.js 22, pnpm (via Corepack) and Docker
- Develop: `corepack enable pnpm && pnpm bootstrap && pnpm dev   # admin at http://localhost:2368/ghost; MySQL, Redis and Mailpit run in Docker`
- Test: `pnpm test`
- Check/lint: `pnpm lint`
- Build: `pnpm build`
- Stack: javascript, typescript, handlebars (Node.js, Express, Bookshelf/Knex, React, Tailwind CSS (Shade), Nx, Vitest). Difficulty for a non-developer with an AI: **moderate**. The look of your site is a theme (Handlebars templates and CSS), which you can change and upload without touching Ghost itself, so most changes are easy. Settings cover branding, navigation, newsletters, memberships and code injection. Ghost's own code is a very large monorepo (Node core, React admin, several embedded apps) and is advanced to change.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `docs/README.md`, `apps/admin/README.md`, `apps/shade/AGENTS.md`.

## Customisation points (settings → extend → code)
- **design-and-branding** [settings]: Logo, colours, fonts, cover image and the options your theme offers, with a live preview. → `Settings → Design & branding (apps/admin/src/settings/site/design-*.tsx); theme settings declared in each theme's package.json`
- **navigation-and-announcement** [settings]: Menu links and a banner across the top of the site. → `Settings → Navigation and Announcement bar (apps/admin/src/settings/site/)`
- **membership-and-newsletters** [settings]: Free and paid plans, the sign-up pop-up, several newsletters and the email design. → `Settings → Membership (portal, tiers, Stripe) and Newsletters (apps/admin/src/settings/membership/, email/)`
- **code-injection** [settings]: Add small bits of CSS or a script (e.g. a booking widget or privacy-friendly analytics) without editing the theme. → `Settings → Code injection (apps/admin/src/settings/advanced/code-injection.tsx), plus per-post code injection`
- **themes** [extend]: Change every page's layout with Handlebars templates and CSS, then upload the theme as a zip. Survives Ghost updates. → `Settings → Design → Change theme / Upload theme; default themes Source and Casper (ghost/content/themes/, git submodules)`
- **integrations-and-webhooks** [extend]: Connect Zapier, Slack, a booking system or your own scripts; publish from another tool. → `Settings → Integrations (custom integrations give Content/Admin API keys and webhooks)`
- **embed-signup** [extend]: Put a newsletter sign-up form on another website. → `Settings → Growth → Embed signup form (apps/admin/src/settings/growth/embed-signup)`
- **admin-ui** [code]: Changes to the admin screens. Read apps/admin/README.md and apps/shade/AGENTS.md first. → `apps/admin/src/** (React, Shade components from apps/shade)`
- **core** [code]: New server behaviour or data. Use the repository skills under .agents/skills/ for endpoints and migrations. → `ghost/core/server/services/**, ghost/core/server/api/endpoints/, ghost/core/server/data/migrations/`

## Must keep working
- Posts, pages, images and the members list. Back up the database and content folder before upgrades, theme changes or code changes.
- Members' sign-in links and paid subscriptions (Stripe connection, tiers and prices).
- Newsletter sending. Test with a small segment before sending to everyone.
- The ghost_head and ghost_foot theme helpers must stay in default.hbs; members, search and comments rely on them.
- Database changes need a migration in ghost/core/server/data/migrations/.

## Staying updatable
Almost everything a small business needs is settings, code injection, a custom theme or an integration, all of which survive Ghost updates. Avoid forking Ghost itself; it changes fast and is large. Upstream merges small, well-tested fixes but wants new features discussed in the forum first, and its CLA lets the Ghost Foundation relicense contributions. Agents should follow AGENTS.md and docs/.

## Data, costs and safety
- Personal data: **yes**. Stored in: MySQL database (posts, members' names and emails, subscriptions) plus the content folder (images, themes, files), in ./data with ghost-docker. Your posts and your members list, including who pays. Back up the database and the content folder; you can also export content (Settings → Migration tools) and members (Members → Export) as files. Card details stay with Stripe, never in Ghost.
- Service: Email (SMTP) for transactional mail (required, free with most providers): Staff invites, password resets and member sign-in links. Ghost needs this to work properly.
- Service: Mailgun (optional, pay-per-use (free trial)): Sending newsletters to many subscribers at once. Ghost's bulk email uses Mailgun.
- Service: Stripe (optional, Stripe's card fees; Ghost takes no cut when self-hosted): Paid memberships, tips and donations.
- Service: Tinybird (optional, free tier, then paid): Web traffic analytics in Ghost Admin.
- Service: ActivityPub (Ghost's hosted service or self-hosted) (optional, free): Lets people follow your site from Mastodon and other social web apps.
- Setting `DOMAIN`: Your site's domain name, used by Caddy to get an HTTPS certificate (ghost-docker .env).
- Setting `DATABASE_PASSWORD` (**secret**: the person enters it themselves, never in chat): MySQL password for Ghost. Set before first start; don't change it afterwards.
- Setting `DATABASE_ROOT_PASSWORD` (**secret**: the person enters it themselves, never in chat): MySQL root password. Set before first start.
- Setting `UPLOAD_LOCATION`: Folder for images, themes and other uploads (default ./data/ghost).
- Setting `GHOST_VERSION`: Docker image tag to pin a version (default 6-alpine).
- Ghost is meant to be public, so run it behind HTTPS (ghost-docker includes Caddy for this) and keep it updated.
- Your members list holds names and email addresses. Limit staff accounts, use strong passwords and keep backups private.
- Admin API keys can publish and delete content. Keep them out of AI chats and shared files.
- Code injection runs on every page for every visitor. Only paste code from sources you trust.
- Sending newsletters needs Mailgun and a properly set-up sending domain, or emails may land in spam.

---

# Customising Ghost

Ghost itself is a very large codebase, but **you almost never need to change it.** The look of your site lives in a *theme*, which you can edit and upload separately, and most business needs are settings or integrations. Stay on levels 1 and 2.

## Level 1: Settings (no code)
- **Design & branding:** logo, icon, accent colour, fonts, cover image and your theme's own options, with a live preview.
- **Navigation and announcement bar:** menu links (primary and footer) and a banner across the top.
- **General:** title, description, time zone, publication language, SEO and social cards, staff accounts and roles.
- **Membership:** the sign-up pop-up ("Portal"), free and paid tiers, Stripe, offers, tips and donations, gift subscriptions, welcome emails.
- **Newsletters:** several newsletters, their design, default recipients. Bulk sending needs Mailgun.
- **Code injection:** CSS or scripts in the site header or footer (site-wide or per post), e.g. a booking widget or a font.
- **Migration tools:** import from Substack, WordPress, Medium and others; export your content.

## Level 2: Extend (no fork)
- **Themes:** start from the default theme (Source or Casper), edit the Handlebars templates (`*.hbs`) and CSS, zip it and upload in Settings → Design → Change theme. Theme docs: https://docs.ghost.org/themes. Updating Ghost keeps your theme.
- **Integrations:** Settings → Integrations for Zapier, Slack, Unsplash and more. A custom integration gives you Content API and Admin API keys and webhooks (e.g. "post published").
- **Content API** (read-only, public key): show your posts on another site or app. **Admin API** (secret key): publish from other tools, import members.
- **Embed signup form:** Settings → Growth puts a newsletter form on any other website.

## Level 3: Code
Read upstream `AGENTS.md`, `docs/README.md` and the nearest package README first. Repository skills in `.agents/skills/` cover endpoints, migrations and Shade components.

| Change | Where |
|---|---|
| Admin screens | `apps/admin/src/**` (React; UI from `apps/shade`) |
| Settings screens | `apps/admin/src/settings/{site,general,membership,email,growth,advanced}/` |
| Sign-up pop-up, comments, search | `apps/portal/`, `apps/comments-ui/`, `apps/sodo-search/` |
| Server features | `ghost/core/server/services/**`, API in `ghost/core/server/api/endpoints/` |
| Data | `ghost/core/server/data/migrations/` (use the create-database-migration skill) |
| Default themes | `ghost/content/themes/source`, `casper` (git submodules of TryGhost/Source and TryGhost/Casper) |

## Running locally
- **Try it:** `npm install ghost-cli -g`, then `ghost install local` in an empty folder; open http://localhost:2368/ghost.
- **Run it for real:** the official Docker set-up at https://github.com/TryGhost/ghost-docker (Ghost, MySQL and Caddy for HTTPS). Copy `.env.example` to `.env`, set the domain, passwords and mail settings, then `docker compose up -d`.
- **Theme work:** run Ghost locally, put your theme folder in `content/themes/`, restart, and switch to it in Settings → Design.
- **Core development:**
  1. Install Node 22, Docker and enable Corepack (`corepack enable pnpm`).
  2. Clone with submodules and run `pnpm bootstrap`.
  3. Run `pnpm dev` (or `pnpm dev:up` in the background) and open http://localhost:2368/ghost.
- **Check:** `pnpm check` runs formatting, lint and unit tests.

## Pitfalls
- Back up first: the database and the content folder. Export members as CSV too.
- Keep the `ghost_head` and `ghost_foot` helpers in your theme's `default.hbs`, or members, search and comments stop working.
- Transactional email (SMTP) must work or staff and members can't sign in.
- Newsletters to large lists need Mailgun and a verified sending domain.
- Don't fork Ghost core for things a theme or code injection can do; core moves fast and merges get painful.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/ghost/db90cf0/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/ghost/db90cf0/SKILL.md)