← Back to all postsRead in English

블로그 만들기: 처음부터 끝까지 따라하는 가이드

이 블로그를 실제로 만든 과정 그대로다. 명령어와 함께, 왜 그렇게 하는지도 한 줄씩 붙였다.

1단계. 뭘 원하는지 정하기

  • 주제 — 기술, 일상, 리뷰, 특정 분야 실무 경험 등. 주제가 분명할수록 나중이 쉬워진다.
  • 배포 방식 — GitHub Pages는 git을 알아야 한다. Cloudflare Pages는 터미널 명령어 한 줄로 끝난다. 이 글은 후자를 쓴다.
  • 디자인 톤 — 심플하게 할지 컬러풀하게 할지 대략만 정해두자. 완벽할 필요는 없다.

2단계. 개발 환경 준비하기

터미널 여는 법(macOS): ⌘ + Space → “터미널” 입력 → Enter.

Node.js가 설치되어 있는지 확인:

node -v
npm -v

버전 번호가 뜨면 통과. 안 뜨면 설치:

brew install node

brew 명령어도 안 된다면 brew.sh에서 Homebrew부터 설치해야 한다.

3단계. Astro로 블로그 뼈대 만들기

Astro는 블로그처럼 글 중심 사이트에 맞는 가벼운 프레임워크다. 한 줄로 템플릿이 만들어진다:

npm create astro@latest -- my-blog --template blog --install --no-git --yes
  • my-blog → 원하는 폴더 이름으로 바꿔도 됨
  • --template blog → 글 목록, 개별 글 페이지, RSS까지 다 포함된 템플릿
cd my-blog
npm run dev

브라우저에서 http://localhost:4321 접속 → 기본 템플릿 블로그가 보이면 정상이다. 파일을 저장할 때마다 자동으로 새로고침된다.

4단계. 기본 정보 바꾸기

템플릿엔 가짜 문구(lorem ipsum)가 들어있다. 이 둘은 꼭 바꾸자.

src/consts.ts:

export const SITE_TITLE = '내 블로그 이름';
export const SITE_DESCRIPTION = '블로그 한 줄 소개.';

src/pages/about.astro: 예시 문구를 지우고 실제 소개로 채운다.

편집은 VS Code 같은 코드 에디터로 하면 편하다. 파일 탐색기 + 미리보기(⌘+Shift+V)가 같이 있어서 코드를 잘 몰라도 접근하기 쉽다.

5단계. Cloudflare Pages 배포 준비

지금은 내 컴퓨터에만 있는 상태다. 남이 보려면 서버에 올려야(배포) 한다.

npm install -D wrangler
npx wrangler login

login 실행하면 브라우저 창이 자동으로 뜬다. 거기서 승인 버튼만 누르면 끝. 계정이 없으면 이 화면에서 무료로 만들 수 있다.

6단계. 실제로 배포하기

주의: 최신 wrangler는 기본적으로 더 복잡한 배포 방식(Workers)으로 자동 전환을 시도하다 실패한다. 프로젝트를 처음 만들 때는 --force를 꼭 붙여서 막는다:

npx wrangler pages project create my-blog --production-branch=main --force

그 다음부턴 이 두 줄이면 끝:

npm run build
npx wrangler pages deploy dist --project-name=my-blog

터미널에 뜨는 https://my-blog.pages.dev가 내 블로그 주소다. 새 글을 올릴 때마다 이 두 줄을 다시 실행해야 실제로 반영된다.

매번 치기 귀찮다면 package.json의 scripts에 추가:

"deploy": "astro build && wrangler pages deploy dist --project-name=my-blog"

이후로는 npm run deploy 한 줄이면 끝.

7단계. 글 쓰는 방법

src/content/blog/ 폴더에 .md 파일 하나 = 글 하나. 파일명이 곧 주소가 된다 (first-post.md → /blog/first-post).

---
title: '글 제목'
description: '한 줄 요약.'
pubDate: 'Sep 18 2026'
---

본문은 여기부터.

--- 사이는 프런트매터(제목·날짜 등 정보), 그 아래가 실제 글 내용이다.

꼭 필요한 마크다운 문법 다섯 가지:

  • **굵게**
  • *기울임*
  • ## 소제목
  • - 목록
  • [링크 글자](주소)

저장하면 /blog에 자동으로 뜬다. 단, 6단계의 배포 명령어를 다시 실행해야 실제 사이트에도 반영된다 — 저장만 해서는 나만 볼 수 있다.

8단계. 디자인 손보기

src/styles/global.css 맨 위 :root { } 안에 색상값들이 모여있다 (예: --accent). 이 값 하나 바꾸면 그 색을 쓰는 버튼·링크·밑줄이 전부 한 번에 바뀐다.

완벽하게 만들려 하지 말고, 일단 배포해서 실제로 보면서 조금씩 고치는 게 더 빠르다.

9단계. 검색엔진에 등록하기 (SEO)

지금은 “존재하는” 사이트지 “검색되는” 사이트가 아니다.

  1. astro.config.mjs의 site 값을 실제 주소로: 
    site: 'https://my-blog.pages.dev',
  2. public/robots.txt 생성: 
    User-agent: *
Allow: /

Sitemap: https://my-blog.pages.dev/sitemap-index.xml
  3. Google Search Console에 등록 — **“도메인”이 아니라 “URL 접두어”**를 고른다. (pages.dev는 내 DNS가 아니라서 “도메인” 방식은 실패한다.) “URL 접두어”는 대신 “HTML 태그” 인증을 쓸 수 있다 — 받은 코드를 src/components/BaseHead.astro의 <head> 안에 붙이고 재배포.
  4. 인증 후 Sitemaps 메뉴에서 sitemap-index.xml 제출.

주의: 제출한다고 바로 검색에 뜨지 않는다. 며칠 걸릴 수 있고, 정상이다. 여러 번 다시 제출해도 안 빨라진다.

10단계. 모바일에서 꼭 확인하기

데스크톱에서 멀쩡해도 폰에서는 이미지가 화면 밖으로 삐져나가는 경우가 흔하다. 원칙 하나: 실제 폰으로 열어보고, 이상하면 그 자리에서 스크린샷. “이상해요”보다 스크린샷 한 장이 훨씬 빨리 원인을 찾게 해준다.

자주 하는 실수

  • npm 명령어가 “command not found” → Node.js 설치부터 다시 확인.
  • 배포했는데 사이트가 안 바뀜 → npm run build를 빼먹었거나, 브라우저 캐시 문제일 수 있다. 새로고침(⌘+Shift+R)해보자.
  • SEO 등록에서 계속 실패 → “도메인” 속성으로 시도했을 가능성이 높다. “URL 접두어”로 다시.

마무리

원하는 것 정하기 → 환경 준비 → Astro 설치 → 정보 채우기 → 배포 준비 → 배포 → 글쓰기 → 디자인 → SEO → 모바일 확인.

완벽하게 시작할 필요 없다. 일단 배포하고, 보이는 문제부터 하나씩 고치면 된다.