04. 글 쓰기·자동 배포·일상 운영 흐름
“셋업은 한 번, 글 쓰기는 매주.”
이것을 왜 배우는가?
지금까지는 사이트 골격을 만들었습니다. 이제부터가 진짜입니다 — 콘텐츠 채우기.
블로그가 망하는 가장 흔한 이유는 글이 0편이거나 5편에서 멈추기 때문입니다. 셋업 1주일 + 글 0편보다 셋업 5분 + 글 30편이 100배 가치 있습니다.
이 단계가 끝나면:
- 마크다운으로 글 쓰는 법 익힘
- 글 추가 → 자동 배포 흐름 체화
- 일상 운영에 필요한 명령어 5개만 외움
마크다운(Markdown)이란?
한 줄 정의
Markdown = “표시(mark)하는 언어(down)”. 일반 텍스트에 특수 기호 몇 개 붙여서 서식(굵게·제목·링크 등)을 표현하는 가벼운 문법.
비유:
워드 문서에서 마우스로 “굵게” 버튼 누르는 것 = 마크다운에서 단어 양옆에
**붙이기. 워드는 GUI(눈으로 보면서), 마크다운은 텍스트 기호로.
왜 마크다운인가
| 마크다운 | 워드 (.docx) | HTML |
|---|---|---|
| 일반 텍스트 파일 | 복잡한 바이너리 | 태그가 많음 |
| 어디서든 열림 | 워드 필요 | 브라우저 필요 |
| 검색 쉬움 | 검색 어려움 | 검색 가능 |
| 버전 관리 잘 됨 | 변경 추적 어려움 | 가능 |
| 1초만에 입력 | 마우스 클릭 여러 번 | 태그 입력 부담 |
**굵게** | Ctrl+B로 굵게 | <strong>굵게</strong> |
→ 글 쓰기에 가장 효율적입니다. 한 번 익히면 평생 씀.
마크다운 핵심 문법 (5분이면 익힘)
제목 (Heading):
# 가장 큰 제목 (H1)
## 큰 제목 (H2)
### 중간 제목 (H3)
#### 작은 제목 (H4)강조:
**굵은 글씨**
*기울임*
~~취소선~~
`인라인 코드`리스트:
- 항목 1
- 항목 2
- 하위 항목 (스페이스 2개 들여쓰기)
- 항목 3
1. 순서 있는 첫째
2. 둘째
3. 셋째링크와 이미지:
[링크 텍스트](https://example.com)
코드 블록:
```javascript
// 이 안에 코드. 색깔 자동 표시
const greeting = 'Hello';
console.log(greeting);
```인용:
> 인용문입니다. 책에서 가져온 글이나 강조할 때 사용.구분선:
---표:
| 헤더1 | 헤더2 |
|-------|-------|
| 셀A | 셀B |
| 셀C | 셀D |⚠️ 이 정도면 99%의 블로그 글에 충분합니다. 나머지 고급 문법은 필요할 때 검색.
Step 1. 첫 글 작성하기
글 파일 만들기
Astro 블로그 템플릿은 src/content/blog/ 폴더 안의 .md 파일을 자동으로 글로 인식합니다.
VS Code/Cursor에서 my-blog 폴더 연 상태로:
- 좌측 폴더 트리에서
src/content/blog/폴더 우클릭 - “New File” 선택
- 파일 이름:
first-post.md
파일 이름 규칙:
- 영문 소문자
- 띄어쓰기 대신 하이픈
-.md확장자- 예:
first-post.md,why-i-built-this.md,2026-04-29-update.md- 이 파일 이름이 URL의 일부가 됨:
yourname.com/blog/first-post
글 기본 구조
first-post.md 파일 안에 다음을 입력:
---
title: '첫 번째 글입니다'
description: '왜 이 블로그를 만들었는지'
pubDate: '2026-04-29'
heroImage: '/blog-placeholder-1.jpg'
---
여기서부터 본문입니다.
## 시작하며
안녕하세요. 김민수입니다.
오늘부터 빌딩 일지를 남기려고 합니다.
주제는:
- AI 활용 빌딩
- 외국인을 위한 한국어 학습 도구
- 1인 개발 시행착오
## 왜 만들었나
3가지 이유:
1. **공개 책임감** — 글로 약속하면 안 멈추게 됨
2. **시드 만들기** — 첫 사용자는 본인 글의 독자에서 옴
3. **자산 누적** — 1년 후의 본인이 가장 큰 수혜자
## 앞으로 계획
매주 1편씩, 진행 중인 프로젝트와 배운 점을 정리하겠습니다.
첫 프로젝트는 이미 작업 중입니다 — 다음 글에서 공개합니다.
---
오늘은 여기까지. 매주 봅시다.Frontmatter 이해하기
위 코드의 맨 위 ---로 둘러싸인 영역을 **Frontmatter(프런트매터)**라고 합니다.
Frontmatter = “문서의 앞쪽 본문”. 책의 표지·저자·출판사 정보와 비슷. 글의 메타정보 담는 곳.
| 필드 | 무엇 | 필수? |
|---|---|---|
| title | 글 제목 (브라우저 탭, 글 목록, SNS 공유 시 표시) | ✅ 필수 |
| description | 글 요약 (검색 결과·SNS 공유 시 표시) | ✅ 필수 |
| pubDate | 발행일 (글 정렬 기준) | ✅ 필수 |
| heroImage | 글 대표 이미지 경로 | 선택 |
| updatedDate | 수정일 | 선택 |
⚠️ Frontmatter 형식 주의:
- 위아래
---정확히 3개씩 - 따옴표
'또는"일관되게 - 콜론
:뒤에 공백 1개 - 들여쓰기 들쭉날쭉하면 에러
❌ 잘못된 예시:
---
title: 첫 글 ← 따옴표 없음 (가능하지만 권장 X)
pubDate:'2026-04-29' ← 콜론 뒤 공백 없음
---✅ 올바른 예시:
---
title: '첫 글'
pubDate: '2026-04-29'
---저장하고 확인
저장 (Cmd+S / Ctrl+S).
만약 npm run dev로 로컬 서버가 켜져 있으면 자동으로 새로고침. 없으면 터미널에서:
cd my-blog
npm run dev브라우저에서 http://localhost:4321/blog/first-post 접속 → 본인 글 보임.
Hero Image 처리
Frontmatter에 heroImage: '/blog-placeholder-1.jpg'가 있는데:
- 이건
public/폴더 안의 이미지 가리킴 - 기본 템플릿에 placeholder 이미지 들어있음
- 본인 이미지 쓰려면
public/폴더에 이미지 넣고 경로 변경:heroImage: '/my-image.jpg' - 이미지 없이 가려면 그 줄 통째로 삭제
Step 2. 글을 인터넷에 올리기
본인 컴퓨터에서만 보이는 글을 인터넷에 띄우려면 git push가 필요합니다.
명령어 3개
터미널에서 my-blog 폴더로 이동 후:
# 1. 변경된 파일 모두 추가
git add .
# 2. commit (저장점 만들기) + 메시지 작성
git commit -m "post: first post"
# 3. GitHub에 업로드 → Cloudflare 자동 배포
git push
git add .= 현재 폴더(.)의 모든 변경사항 추가.git commit -m "..."= 저장점 만들기 + 메시지.-m은 message의 줄임.git push= GitHub에 업로드.
자동 배포 확인
git push 후:
- Cloudflare 대시보드 열기
- 프로젝트 → Deployments 탭
- 새 배포가 시작됨 (1~2분)
- 완료되면 본인 사이트(
my-blog-xxxx.pages.dev) 새로고침 - 새 글이 메인 페이지·블로그 목록에 보임
✅ 첫 글이 인터넷에 올라간 순간. 축하합니다.
커밋 메시지 형식 권장
매번 git push 시 commit 메시지가 필요. 일관성 있게 쓰면 나중에 변경 이력 볼 때 편함.
| 형식 | 예시 |
|---|---|
post: 글 제목 | post: first post |
update: 무엇을 수정 | update: fix typo |
style: 디자인 변경 | style: change header color |
feat: 새 기능 | feat: add comment section |
fix: 버그 수정 | fix: broken image link |
🟡 INFERRED — 이건 권장 형식 (Conventional Commits 일부 따름). 강제 아님. 본인 편한 대로.
Step 3. 일상 글 쓰기 흐름
매번 반복하는 5단계
1. VS Code/Cursor 열기
2. src/content/blog/ 안에 새 .md 파일 만들기
3. 글 작성 (Frontmatter + 본문)
4. 저장 + 로컬 미리보기 (npm run dev로 확인)
5. git add . && git commit -m "post: ___" && git push이게 전부입니다. 한 번 익숙해지면 5분이면 가능.
효율 팁
팁 1: VS Code에서 마크다운 미리보기
VS Code: 마크다운 파일 열고 Cmd+Shift+V (Mac) / Ctrl+Shift+V (Windows) → 우측에 미리보기 창.
팁 2: 한 명령어로 add+commit+push
매번 3개 명령어 치기 귀찮으면:
# 한 줄로
git add . && git commit -m "post: 글 제목" && git push팁 3: 글 초안 따로 보관
발행 전 글은 src/content/blog/ 대신 다른 폴더에 두면 사이트에 안 올라감:
my-blog/
├── drafts/ ← 초안 (사이트에 안 올라감)
│ └── future-post.md
└── src/
└── content/
└── blog/ ← 발행한 글만
└── first-post.md⚠️ drafts/는 본인이 임의로 만든 폴더. Astro가 자동으로 인식 안 하므로 안전.
팁 4: AI에게 초안 시키기
Cursor에서:
“이번 주 빌딩 일지 글 초안 써줘. 주제는 ___, 길이는 800자 정도, 진솔하고 구체적으로.”
→ AI가 초안 작성. 본인이 다듬어서 발행.
Step 4. 글 수정과 삭제
글 수정
이미 발행한 글 수정:
# 1. .md 파일 열고 수정
# 2. 저장
# 3. git push (메시지: update: fix typo 등)
git add .
git commit -m "update: fix typo in first post"
git push→ 1~2분 후 사이트에 반영.
⚠️ URL은 파일 이름에 의존. first-post.md → first-post-revised.md로 바꾸면 URL도 바뀜 → 외부 링크 깨짐. 글 내용 수정은 OK, 파일 이름 변경은 신중히.
글 삭제
# 1. .md 파일 삭제 (VS Code 우클릭 → Delete)
# 2. git push
git add .
git commit -m "remove: outdated post"
git push→ 사이트에서 사라짐. 단 GitHub git history에는 남음 (완전 삭제 아님).
글 비공개로 전환
삭제 대신 임시로 숨기고 싶으면 drafts/ 폴더로 이동:
mv src/content/blog/old-post.md drafts/
git add .
git commit -m "draft: hide old post"
git push→ 사이트에서 사라지지만 본인은 파일 보유.
Step 5. 글쓰기 자체에 집중하는 팁
글감 부족 해결법
아이디어 노트 운영:
drafts/ideas.md 같은 파일에 떠오르는 글감 메모:
# 블로그 글감 모음
## 작성 예정
- [ ] 왜 노션 대신 옵시디언으로 갔는가
- [ ] AI 첫 사용자 10명 만든 이야기
- [ ] Cursor 1개월 사용 후기
## 추후 검토
- [ ] 외국어 학습 앱 시장 분석
- [ ] 디스콰이엇 vs 트위터 6개월 운영 비교
## 보류
- ...매일/매주 글 쓰기 정착
| 페이스 | 추천 상황 |
|---|---|
| 매일 1편 | 의지 강함 + 시간 많음. 90%가 1주에 포기 |
| 주 1편 | 가장 현실적. 1년 = 50편 누적 |
| 격주 1편 | 직장인 + 깊이 있는 글. 1년 = 25편 |
| 월 1편 | SEO 효과 거의 없음. 비추 |
🟡 INFERRED — 주 1편이 1인 개발자 인디 해커 표준. Marc Lou·Tony Dinh 등도 비슷.
글 길이 가이드
| 글 종류 | 권장 길이 |
|---|---|
| 짧은 업데이트 (“이번 주 한 일”) | 500~1,000자 |
| 일반 빌드 일지 | 1,500~3,000자 |
| 깊이 있는 회고 / 가이드 | 3,000~10,000자 |
| SEO 노리는 가이드 글 | 3,000자+ (Google이 깊이 있는 글 우대) |
⚠️ 글 길이 ≠ 가치. 1,000자 정직한 글 > 5,000자 빈말 글.
정리 및 체크리스트
□ 마크다운 문법 5가지 (제목·강조·리스트·링크·코드 블록) 익힘
□ src/content/blog/first-post.md 파일 만들고 Frontmatter 정확히 작성
□ 로컬에서 npm run dev로 글 미리보기 확인
□ git add . && git commit -m "..." && git push 흐름으로 인터넷에 올림
□ Cloudflare에서 자동 배포 완료 확인
□ 본인 사이트 주소(my-blog-xxxx.pages.dev)에서 글 보임
□ 글 추가/수정/삭제 흐름 한 번씩 시도해봄흔한 실수 모음
| 실수 | 결과 | 해결 |
|---|---|---|
Frontmatter --- 안 씀 | 빌드 에러 | 위아래 --- 정확히 3개 |
| Frontmatter pubDate 형식 틀림 | 빌드 에러 | 'YYYY-MM-DD' 형식 (따옴표 포함) |
| 파일 이름에 한글/공백 | URL 깨짐 | 영문 소문자 + 하이픈만 |
| heroImage 경로 잘못됨 | 이미지 안 보임 | public/ 폴더 기준 절대 경로 (/로 시작) |
commit 메시지 안 쓰고 git commit | 에디터 모드 진입 | :wq 입력해서 빠져나오기. 다음부턴 -m "메시지" 잊지 않기 |
| git push 시 인증 만료 | ”permission denied” | 브라우저로 GitHub 재인증 |
| 마크다운 표 정렬 깨짐 | 표가 일반 텍스트로 | 헤더 행과 구분선 정확히 (예: ` |
자주 묻는 질문
Q: 영어로 써야 하나요? 한국어 써도 되나요?
A: 둘 다 OK. 글로벌 SEO 노리면 영어, 한국 시장이면 한국어. 처음엔 본인 편한 언어가 정답 (영어 부담으로 안 쓰면 의미 없음).
Q: 글에 영상이나 이미지 넣을 수 있나요?
A:
- 이미지:
public/images/폴더에 넣고 - GIF: 이미지와 동일 처리
- YouTube 영상: 마크다운에
<iframe src="https://www.youtube.com/embed/VIDEO_ID" ...>직접 삽입
Q: 댓글 기능 추가하고 싶어요
A: Giscus (GitHub Discussions 기반, 무료) 추천. AI에 “Astro에 Giscus 댓글 추가해줘” 물어보면 코드까지 줌.
Q: 방문자 통계 보고 싶어요
A: 옵션 두 가지:
- Google Analytics (무료, 표준)
- Plausible Analytics (간결, 유료 $9/월)
→ AI에 “Astro에 Plausible Analytics 추가해줘”
Q: 다크 모드 지원하고 싶어요
A: 기본 Astro 블로그 템플릿이 다크 모드 일부 지원. 디자인 더 다듬으려면 AI에 요청.
💡 핵심 포인트
이 단계의 핵심: .md 파일 만들고 git push 하면 글이 인터넷에 올라간다.
5분이면 끝나는 흐름이라 한 번만 익히면 평생 씁니다. 이제부터 진짜 콘텐츠를 만들 차례입니다.
다음 단계
- 05-monetize.md — 광고(애드센스) 추가, 본인 도메인 연결 (선택)
- 06-troubleshooting.md — 자주 막히는 문제 해결