Ghost Contributor Documentation

Welcome to the Ghost contributor documentation! This guide will help you understand the codebase, set up your development environment, and start contributing to Ghost.

Quick Start

Prerequisites

• Node.js - Recommended to install via nvm
• pnpm - Package manager
• Docker - For MySQL database and development services

Initial Setup

1. Fork and Clone

First, fork the Ghost repository on GitHub, then:

# Clone your fork with submodules
git clone --recurse-submodules [email protected]:<YourUsername>/Ghost.git
cd Ghost

# Configure remotes
git remote rename origin upstream
git remote add origin [email protected]:<YourUsername>/Ghost.git

2. Install and Setup

# Install dependencies and initialize submodules
corepack enable pnpm
pnpm run setup

3. Start Ghost

# Start development (runs Docker backend services + frontend dev servers)
pnpm dev

Ghost will be available at:

• Main site: http://localhost:2368/
• Admin panel: http://localhost:2368/ghost/

Troubleshooting Setup

If you encounter issues during setup:

# Fix dependency issues
pnpm fix

# Update to latest main branch
pnpm main

# Reset running dev data
pnpm reset:data

Repository Structure

Ghost/
├── apps/              # Frontend applications
│   ├── admin-x-*/     # New React-based admin apps
│   ├── portal/        # Member portal
│   ├── comments-ui/   # Comments widget
│   ├── signup-form/   # Signup form widget
│   └── ...
├── ghost/             # Core Ghost application
│   ├── core/          # Main Ghost backend
│   ├── admin/         # Admin build output
│   └── i18n/          # Internationalization
├── e2e/               # End-to-end tests
├── adr/               # Architecture Decision Records

Contributing

Before contributing, please read:

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

Finding Issues to Work On

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

Development Workflow

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

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

Architecture Decision Records

The adr/ directory contains Architecture Decision Records (ADRs) that document significant architectural decisions made in the project.

Getting Help

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

License

Ghost is open source software licensed under the MIT License.