Ghost is a strong writing tool. Paying for a live Ghost server is a poor fit when the public site only needs HTML. Ghost on GitHub Pages keeps the editor on your computer and publishes a static blog on GitHub Pages, which is free for a public repository.
This is the 2026 path. The current docs add Docker Compose for the editor and a GitHub Actions workflow that builds the static site. The earlier walkthrough, Publish a Ghost Blog on GitHub Pages with the v3 Release, still matches install.sh on the v3.0.0 tag. Use that article when you want the shell installer line by line. Use this one when you want the template, Docker, or Actions.
A current example is the v3 demo.
What stays on your machine
Ghost Admin is not part of the public site. You edit at http://localhost:2373/ghost. The tool gssg (the npm package ghost-static-site-generator) reads that local site and rewrites localhost links to your GitHub Pages URL. A validator then rejects HTML that still points at localhost:2373 or localhost:2368, and it rejects a few broken image suffixes that showed up in older exports.
GitHub Pages serves the generated files. Visitors do not get a Ghost login, member billing, or a dynamic Content API. That tradeoff is what makes the hosting free. If your site depends on those live Ghost features, this setup is the wrong host.
Prerequisites
You need a GitHub account and a public repository. For the Actions path, set Pages to GitHub Actions as the source. The workflow uses the built-in GITHUB_TOKEN. You do not add a personal access token for the Pages deploy.
The Docker guide needs Docker with Compose v2. On Windows, use WSL2. Publishing with deploy.sh from that same machine still needs Node.js LTS and wget on the host, because gssg runs outside the Ghost container.
The installer path is Getting Started. It asks for Node.js, npm, wget, and git. Python is not required. Classic v2 needed Python. Current v3 does not.
Check the host tools before you start, in a Unix-like terminal:
node --version wget --version docker compose version docker compose version matters only for the Compose path. The template path runs Docker inside GitHub Actions, so your laptop does not need Docker until you want a local editor.
Start from the template
The shortest CI setup is the starter repository. The demo repository is a published site, so do not use that as your source. The starter is the template.
- Click Use this template and create your own public repository.
- Open Settings, then Pages, and set Source to GitHub Actions.
- Copy your Ghost content into
content/before the posts matter. The paths arecontent/data(includingghost.db),content/images, andcontent/themes. - Push to
mainormaster.
The workflow calls paladini/ghost-on-github-pages/.github/workflows/publish-static.yml. It fills your username and repository name, so a project site is published at https://USER.github.io/REPO. If the repository is named USER.github.io, that automatic URL is wrong. Edit production_domain to https://USER.github.io and set gh_repo to USER.github.io.
If content/ only contains the template README, Ghost can boot a fresh site and the first publish can be the default welcome page. Replace the folder with a real snapshot and push again when you want your own posts. The workflow refuses to run when the content/ directory is missing, unless you set allow_empty to true. A README keeps the directory present, which is why the welcome page can appear.
Do not commit .env files, mail credentials, or payment keys. The public repository should hold only the content snapshot you are willing to publish, plus the workflow file.
Edit with Docker, then publish
If you would rather not install Ghost with ghost-cli, use Compose. The compose file uses the official ghost:6 image. It is not a rebuilt Ghost. Your posts stay in ~/.ghost/content/data/ghost.db on the host.
From a clone of the toolkit:
chmod +x scripts/compose-setup.sh ./scripts/compose-setup.sh docker compose up -d Open http://localhost:2373/ghost and create the admin user. Write a short test post. When it is ready:
cd ~/.ghost ./deploy.sh deploy.sh runs gssg against http://localhost:2373, validates the HTML, and pushes the static files. The first run asks for your GitHub username, repository name, and remote URL, then stores them in ~/.ghost/deploy.conf. Point that remote at a repository that should contain only the generated site. The script force-pushes its Pages branches. Confirm the remote before the first publish, and do not aim it at a repository that holds unrelated work.
There is also an exporter image, paladini/ghost-on-github-pages:exporter on Docker Hub. The repository workflow publishes the same tag to ghcr.io/paladini/ghost-on-github-pages. The image contains Node.js, wget, and gssg. It does not start Ghost, and it is not a copy of ghost:6. Ghost must already be running. On Linux or WSL:
docker run --rm --network host \ -e GH_USERNAME=yourname \ -e GH_REPO=your-repo \ -e GHOST_INSTALL=/ghost \ -v "$HOME/.ghost:/ghost" \ paladini/ghost-on-github-pages:exporter That writes ~/.ghost/publish/. It does not push to GitHub. Docker Desktop on Windows does not share the Linux host network. Use -e GHOST_SERVER_URL=http://host.docker.internal:2373 instead of --network host. If the pull fails, use deploy.sh. The image is only a way to avoid installing Node on the machine that runs the export.
Check the result
Do not stop when the command exits 0. Open the Pages URL and check the home page, one post, one tag, and one image. A broken export often looks fine on the home page and fails on the next link.
Locally you can run:
cd ~/.ghost ./scripts/validate-static.sh static In CI the same script runs before the artifact is uploaded. Give GitHub Pages a few minutes after the first deploy. The CI guide describes both the reusable workflow and the Marketplace action.
The v3 demo is the reference for a successful current site. Compare your home page, a post, and an image with that demo when you are unsure whether the publish worked.
Limits
This is not Ghost(Pro) and it is not a public Ghost server. Comments, members, and subscriptions that need a live Node process will not work on the static site. Search that depends on Ghost's Content API will not work either. Newsletters that Ghost sends from the admin app also stay on your computer, because the public host has no Ghost process.
The Marketplace action in the toolkit root runs the same export and uploads a Pages artifact. GitHub cannot call the reusable workflow from inside that composite action, so the deploy step is a second job. The starter uses the reusable workflow, which is the shorter file. Pick the starter unless you specifically want the action listed for Marketplace search.
JSR is the wrong registry for this project. The toolkit is shell, Compose, and a GitHub Action. It is not a JavaScript module you import.
Takeaway
Pick one path and publish a test post before you move a real archive. The template is the shortest CI path. Docker Compose is the shorter editor path on Windows with WSL. install.sh remains the path from the v3.0.0 article, and Getting Started is still the checklist for that install.
If you already publish a static Ghost blog another way, which check would you want in CI first: localhost links, missing images, or a diff of the generated HTML?
AI assistance disclosure
AI assistance was used to organize this tutorial and match the repository docs. The commands and limits were checked against the toolkit on master, including compose.yaml, the publish workflow, the starter template, and the v3 guides. The exporter image is published by the repository workflow. If a pull of that image fails, use deploy.sh, which does not depend on the image.
