Skip to content

README.md

Latest commit

 

History

History
158 lines (118 loc) · 6.11 KB

README.md

File metadata and controls

158 lines (118 loc) · 6.11 KB
Raw

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 git@github.com:TryGhost/Ghost.git
cd Ghost

pnpm setup
pnpm dev

Ghost will be available at:

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:

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

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

Finding Issues to Work On

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 formatting checks, 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

Getting Help

License

Ghost is open source software licensed under the MIT License.