Ghost Codebase Documentation

Welcome to the Ghost codebase documentation! These docs are for anyone wanting to work on the Ghost codebase. For self-hosting, themes, or using Ghost APIs, see the official Ghost documentation.

Quick Start

With the prerequisites installed:

git clone --recurse-submodules [email protected]:TryGhost/Ghost.git
cd Ghost

pnpm setup
pnpm dev

Ghost will be available at:

• Main site: http://localhost:2368
• Admin panel: http://localhost:2368/ghost/
• Development email: http://localhost:8025

pnpm dev also starts the supporting MySQL and Redis containers, plus Admin and Portal development watchers.

For more detail, see the development setup guide including first-run setup, development variants, and troubleshooting.

Repository Structure

Ghost/
├── apps/              # Admin and public frontend apps
│   ├── admin/          # React Admin
│   ├── ember-admin/    # Legacy Ember Admin
│   ├── portal/         # Member Portal
│   ├── comments-ui/    # Comments
│   └── shade/          # Admin design system
├── ghost/core/        # Ghost server and frontend rendering
│   ├── core/server/    # APIs, models, and services
│   ├── core/frontend/  # Theme rendering and helpers
│   ├── content/        # Default themes, adapters, and local content
│   └── test/           # Server tests
├── koenig/            # Editor and content-format packages
├── packages/          # Shared libraries and adapter contracts
├── configs/           # Shared build, lint, test, and TypeScript config
├── e2e/               # Browser end-to-end tests
├── docker/            # Local development containers and services
└── scripts/           # Repository tooling

pnpm links the workspaces and Nx runs their tasks in dependency order. For more detail, see the monorepo structure guide. The configuration guide explains how Ghost Core loads defaults, local overrides, environment variables, and secrets. The authentication guide maps staff, integration, and member authentication to the current codebase.

Contributing a change

Before contributing, please read:

1. Contributing Guide - Guidelines for contributions
2. Code of Conduct - Community standards

To contribute or add translations, see Translating Ghost. For more detail on adding translatable product copy, see the internationalization guide.

Guides

Codebase guides explain how the main systems fit together:

• Authentication
• Configuration
• Database structure
• Internal caching
• Jobs system
• Post analytics
• Site UUID
• Stripe flows
• Theme compatibility

Practice and contributor guides explain how to make and verify changes:

• API design
• Database migrations
• Browser E2E testing
• Codebase documentation
• Email testing
• Error handling
• Internationalization
• Performance testing
• Testing development URLs and devices

Reference guides provide tables and other information to look up while working on Ghost:

• Node.js compatibility

Finding Issues to Work On

• Good First Issues - Great for newcomers
• Help Wanted - Issues that need attention

Development Workflow

1. Clone the repository
2. Create a branch for your changes
3. Make your changes and write tests
4. Run pnpm check to ensure everything works
5. Commit following our commit message conventions
6. Submit a pull request to the main branch

For more detail, see the contribution workflow.

Testing

Use pnpm check as the default one-stop command for linting and testing. Add tests at the closest layer to the behavior you changed. Browser end-to-end tests and Ember Admin tests run separately from pnpm check.

For more detail, see the testing guide including how to choose a test suite, run focused tests, and use the separate browser and Ember Admin test lanes.

Shipping

Admin uses continuous delivery on Ghost(Pro), so every commit to main can ship before the next server release. Keep Admin compatible with server versions that are still live. Public Ghost releases include Admin and the server every Tuesday.

For more detail, see the shipping guide including when changes reach Ghost(Pro), self-hosted installs, npm, jsDelivr, and the Docker Official Image.

Additional Resources

• Official Documentation - User and developer docs
• Ghost Forum - Community support and discussions
• API Documentation - Content and Admin API reference
• Theme Documentation - Theme development

Getting Help

• Forum: forum.ghost.org
• Support: See SUPPORT.md
• Issues: GitHub Issues

License

Ghost is open source software licensed under the MIT License.