Ghost 테마 커스터마이징: macOS 로컬 개발 환경에서 Ruby 테마 수정하기

Ghost 테마 커스터마이징 시작

Ghost 블로그를 설치한 후, 이제 테마를 직접 수정해보기로 했다. 많은 수정보다는 구조를 파악하고, 기본 폰트를 한글에 잘 어울리는 Pretendard로 교체하고, 검색로봇 설정을 위한 robots.txt 파일을 추가하는 것이 목표다. 워드프레스도 그렇고 고스트에서 제공하는 폰트들이 아무래도 영어에 적합한 폰트들로 되어 있어, 이과정은 필수 라고 생각한다.

1. 로컬에 Ghost 개발 환경 구성

우선 테마를 수정하려면 Ghost의 개발 환경이 필요하다. 이를 위해 macOS에 다음 툴들을 설치했다.

• nvm : Node.js 버전 관리를 쉽게 하기 위해
• Node.js: Ghost가 권장하는 버전 설치 (현재 기준: v20.x)
• yarn: Ghost 테마 개발에 필요한 패키지 매니저

관련 내용은 지난 포스팅에서 정리를 했었다.

2. Ghost 실행 상태 확인

터미널에서 Ghost 설치 디렉터리로 이동한다.

cd ~/ghost-dev

설치된 Ghost 인스턴스의 상태를 확인한다.

ghost ls

┌─────────────┬──────────────┬─────────┬─────────┬─────┬──────┬─────────────────┐
│ Name        │ Location     │ Version │ Status  │ URL │ Port │ Process Manager │
├─────────────┼──────────────┼─────────┼─────────┼─────┼──────┼─────────────────┤
│ ghost-local │ ~/ghost-dev  │ 5.129.1 │ stopped │ n/a │ n/a  │ n/a             │
└─────────────┴──────────────┴─────────┴─────────┴─────┴──────┴─────────────────┘

현재 고스트가 실행되지 않은 상태이다. 실행되지 않은 상태라면 시작한다.

ghost start

시작 후 크롬이나 웹브라우저에서 http://localhost:2368/ghost/로 접속하면 관리자 페이지로 이동할 수 있다.

3. 테마 다운로드 및 적용

Ghost는 기본적으로 ruby 테마를 내장하고 있지만, yarn 관련 문제가 있어 GitHub에서 수동으로 받기로 했다.

• 테마 저장소: https://github.com/TryGhost/Ruby
• 다운로드: 페이지 내 Instructions > Download this theme 참고

이전에 설치된 기본 ruby 테마가 헷갈릴 수 있어 제거한다.

rm -rf ~/ghost-dev/content/themes/ruby

이후 Ghost 관리자 페이지의
설정 아이콘 > Design > Theme > Upload
에서 다운로드한 ZIP 파일을 업로드하면 테마 적용이 완료된다.

4. 테마 폴더 이동 및 개발환경 설정

cd ~/ghost-dev/content/themes/ruby
yarn install

Node.js와 yarn이 미리 설치되어 있어야 한다.

yarn이 설치되어 있지 않다면 전역으로 설치해 준다.

npm install -g yarn

테마폴더(/ghost-dev/content/themes/ruby)에서 로컬 개발을 위한 빌드 도구 실행:

yarn dev

이 명령어는 변경사항을 실시간으로 반영하고, 빌드된 결과는 assets/built/screen.css로 생성된다.

5. Ruby 테마 디렉토리 구조

├── assets
├   ├─ built
├   ├─ css
├   ├─ fonts
├   ├─ images
├   └──js 
├── dist
├── node_modules
├── partials
├── author.hbs
├── default.hbs
├── gulpfile,js
├── index.hbs
├── LICENSE
├── page.hbs
├── psot.hbs
├── README.MD
└── tag.hbs

assets>css에 있는 css파일을 수정해야 한다. yarn dev 가 실행된 상태에서 assets>css 폴더에 css파일을 수정하면 자동으로 built의 screen.css로 병합, 압축되어 진다.

6. Pretendard 폰트 적용

폰트 정의 파일을 수정한다.

VSCode같은 IDE에서 assets/css/general/font.css를 열어 모든 내용을 지우고 아래 코드만 추가한다:

@import url("https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard-dynamic-subset.min.css");

폰트 적용 대상인 assets/css/general/basics.css 파일을 열고 아래 내용을 수정한다. 기존 폰트 설정을 다음과 같이 변경한다:

--font-sans: Pretendard, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif;

이 설정은 모든 페이지에 전역 적용된다.

5. 검색 로봇 설정 (robots.txt)

테마 루트 폴더에 robots.txt 파일을 생성한다.

User-agent: *
Allow: /
Disallow: /ghost/
Sitemap: https://mangobox.co.kr/sitemap.xml

6. 테마 압축 및 업로드

작업이 끝났으면 yarn dev를 종료한다:

Ctrl + C

이후 테마를 zip 파일로 압축한다.

yarn zip

자동으로 dist 폴더에 테마 압축 파일이 생성된다.

├── assets
├── dist
├   └──ruby.zip 

이 파일을 운영 중인 Ghost 관리자 페이지에 업로드하면 커스터마이징이 적용된다.

개발툴 추천

간단한 수정이라 메모장으로도 가능하지만, 편의를 위해 IDE를 사용하는 것을 추천한다. 대표적인 선택지:

• VSCode (가볍고 익숙함)
• Cursor AI (AI 기반 최신 편집기)
• WebStorm (JetBrains 기반 전문 IDE)

마무리

이제 테마의 구조도 이해했고, 폰트도 변경했고, 검색 설정도 마쳤다.
Ghost는 생각보다 구조가 단순하고, 익숙해지면 커스터마이징이 쉬운 플랫폼이다.
자신만의 스타일로 블로그를 꾸미기에 충분히 좋은 시작이었다.