마크다운 글쓰기와 카테고리 관리 — 체계적인 블로그 운영법

안녕하세요, 자바파커입니다.

지금까지 Gatsby 블로그를 설치하고, 스킨을 커스터마이징하는 방법을 다뤘습니다. 이번 포스팅에서는 실제 글을 작성하고 콘텐츠를 체계적으로 관리하는 방법을 알아보겠습니다. 마크다운 문법부터 frontmatter, 태그 전략, 시리즈 기능, 이미지 관리까지 블로그 운영에 필요한 모든 것을 다룹니다.

마크다운 기본 문법

마크다운은 텍스트 기반의 경량 마크업 언어입니다. 기술 블로그에서 가장 많이 사용되는 문법들을 정리합니다.

제목 (Heading)

# 기호의 개수로 제목 수준을 구분합니다.

# h1 — 포스트 제목 (frontmatter title과 중복되므로 본문에서는 사용하지 않습니다)
## h2 — 주요 섹션
### h3 — 하위 섹션
#### h4 — 세부 항목

팁: 본문에서는 ##(h2)부터 시작하는 것이 SEO와 문서 구조에 좋습니다. h1은 포스트 제목이 자동으로 사용합니다.

텍스트 서식

**굵게** 또는 __굵게__
*기울임* 또는 _기울임_
~~취소선~~
`인라인 코드`

결과:

굵게
기울임
~~취소선~~
인라인 코드

순서 없는 목록:
- 항목 1
- 항목 2
  - 중첩 항목 2-1
  - 중첩 항목 2-2

순서 있는 목록:
1. 첫 번째
2. 두 번째
3. 세 번째

코드 블록

기술 블로그의 핵심 요소입니다. 백틱 세 개(```)로 감싸고 언어를 지정합니다.

```javascript
const greeting = "안녕하세요!";
console.log(greeting);
```

```python
def hello():
    print("안녕하세요!")
```

```bash
npm install gatsby-cli -g
```

지원되는 주요 언어 키워드: javascript, typescript, python, java, bash, css, html, json, yaml, sql, go, rust, kotlin, swift 등

표 (Table)

| 기능 | 설명 | 필수 여부 |
|------|------|----------|
| title | 포스트 제목 | 필수 |
| description | 짧은 설명 | 권장 |
| date | 작성일 | 필수 |
| tags | 태그 목록 | 권장 |

결과:

기능	설명	필수 여부
title	포스트 제목	필수
description	짧은 설명	권장
date	작성일	필수
tags	태그 목록	권장

인용 (Blockquote)

> 이것은 인용문입니다.
> 여러 줄로 작성할 수 있습니다.

> **참고**: 강조 표시와 함께 사용하면 주의사항이나 팁을 효과적으로 전달할 수 있습니다.

참고: 강조 표시와 함께 사용하면 주의사항이나 팁을 효과적으로 전달할 수 있습니다.

링크와 이미지

[링크 텍스트](https://example.com)
[새 탭에서 열기](https://example.com){:target="_blank"}

![이미지 대체 텍스트](./images/example.png)
![외부 이미지](https://example.com/image.png)

구분선

---

세 개 이상의 하이픈(-), 별표(*), 밑줄(_)로 구분선을 만들 수 있습니다.

Frontmatter 구조

Frontmatter는 마크다운 파일 상단에 YAML 형식으로 작성하는 메타데이터입니다. gatsby-starter-hoodie에서 지원하는 필드를 자세히 알아봅시다.

기본 구조

---
title: "포스트 제목"
description: "포스트에 대한 짧은 설명 (SEO 메타 설명에 사용됩니다)"
date: 2026-04-04
update: 2026-04-04
tags:
  - gatsby
  - blog
series: "시리즈 이름"
---

각 필드 상세 설명

title (필수)

포스트의 제목입니다. HTML <title> 태그와 <h1> 태그에 사용됩니다.

title: "Gatsby로 GitHub 블로그 시작하기 — 설치부터 첫 배포까지"

큰따옴표로 감싸는 것이 안전합니다. 특히 콜론(:)이 포함된 경우 반드시 따옴표가 필요합니다.
SEO를 위해 핵심 키워드를 앞쪽에 배치합니다.
50~60자 이내가 검색 결과에서 잘리지 않아 적절합니다.

description (권장)

포스트에 대한 짧은 설명으로, 검색엔진 결과와 블로그 목록에 표시됩니다.

description: "Gatsby 설치부터 gatsby-starter-hoodie 테마 적용, GitHub Pages 배포까지 완전 가이드"

120~160자 이내가 적절합니다.
핵심 키워드를 자연스럽게 포함합니다.
클릭을 유도하는 명확한 문장을 작성합니다.

date / update

작성일과 수정일입니다. YYYY-MM-DD 형식으로 작성합니다.

date: 2026-04-04
update: 2026-04-04

date: 포스트 최초 작성일입니다. 목록 정렬에 사용됩니다.
update: 포스트 수정일입니다. 포스트를 업데이트했을 때 갱신합니다.

series

여러 포스트를 하나의 시리즈로 묶을 때 사용합니다.

series: "GitHub 블로그 A to Z"

같은 series 값을 가진 포스트들이 자동으로 그룹핑되어 포스트 하단에 시리즈 네비게이션이 표시됩니다.

폴더 구조 설계

블로그가 커지면 폴더 구조가 매우 중요해집니다. 처음부터 체계적으로 설계하면 나중에 관리가 편합니다.

네이밍 규칙

폴더와 파일 이름에 일관된 규칙을 적용합니다.

카테고리 폴더: 소문자 영문, 하이픈(-) 구분 (예: gatsby-blog, javascript)
포스트 폴더: 시리즈의 경우 번호 접두사 사용 (예: 01-getting-started)
단독 포스트: 핵심 키워드로 구성 (예: closure-explained)
TIL: 날짜 접두사 사용 (예: 2026-03-28-css-grid)
이미지 폴더: 포스트 폴더 내 images/ 하위에 관리

왜 index.md를 사용하는가?

포스트마다 폴더를 만들고 index.md를 사용하는 이유가 있습니다.

# 이렇게 하면
posts/my-post.md          # 이미지를 어디에 둘지 애매합니다

# 이렇게 하면
posts/my-post/index.md    # 관련 이미지를 같은 폴더에 둘 수 있습니다
posts/my-post/images/screenshot.png

이미지를 같은 폴더에 두면 상대 경로(./images/screenshot.png)로 참조할 수 있어 관리가 훨씬 편합니다.

태그 전략

태그를 잘 설계하면 독자가 관련 글을 쉽게 찾을 수 있고, SEO에도 도움이 됩니다.

태그 작성 규칙

소문자 통일: JavaScript 대신 javascript, React 대신 react를 사용합니다.
하이픈 구분: 두 단어 이상인 경우 하이픈으로 연결합니다. (예: github-pages, styled-components)
복수형 지양: algorithms 대신 algorithm처럼 단수형을 사용합니다.
의미 있는 태그: 기타, 잡담 같은 모호한 태그는 피합니다.
적정 개수: 포스트당 3~5개가 적절합니다. 너무 많으면 태그의 의미가 희석됩니다.

태그 분류 체계

태그를 기술/도구/개념/시리즈로 분류하면 체계적으로 관리할 수 있습니다.

# 기술/언어 태그
tags: [javascript, typescript, python, java, go]

# 프레임워크/도구 태그
tags: [gatsby, react, next.js, docker, github-actions]

# 개념 태그
tags: [algorithm, data-structure, design-pattern, clean-code]

# 유형 태그
tags: [tutorial, review, til]

태그 관리 스프레드시트

블로그가 커지면 태그 목록을 별도로 관리하는 것이 좋습니다. 간단한 표를 만들어 사용 중인 태그와 포스트 수를 추적합니다.

태그	포스트 수	비고
gatsby	6	블로그 시리즈
javascript	12	주력 언어
react	8	프론트엔드
til	25	Today I Learned

시리즈 기능 활용

gatsby-starter-hoodie의 시리즈 기능은 연관된 포스트를 그룹으로 묶어주는 강력한 기능입니다.

시리즈 설정 방법

frontmatter에 같은 series 값을 지정하면 자동으로 시리즈가 생성됩니다.

# 포스트 1
---
title: "Gatsby 블로그 시작하기"
series: "GitHub 블로그 A to Z"
date: 2026-04-01
---

# 포스트 2
---
title: "블로그 스킨 커스터마이징"
series: "GitHub 블로그 A to Z"
date: 2026-04-04
---

# 포스트 3
---
title: "마크다운 글쓰기와 카테고리 관리"
series: "GitHub 블로그 A to Z"
date: 2026-04-07
---

이렇게 설정하면 각 포스트 하단에 시리즈 목록이 자동으로 표시되어, 독자가 이전/다음 포스트로 쉽게 이동할 수 있습니다.

시리즈 네이밍 팁

시리즈 이름은 한국어로 작성해도 됩니다. 태그와 달리 시리즈 이름은 URL에 직접 사용되지 않습니다.
명확하고 구체적인 이름을 사용합니다. (예: "GitHub 블로그 A to Z", "React 핵심 개념 정리")
시리즈 내 포스트 순서는 date 값으로 결정됩니다. 날짜를 순차적으로 설정하면 원하는 순서대로 표시됩니다.

시리즈 활용 사례

시리즈 1: "GitHub 블로그 A to Z"
├── 01. Gatsby로 GitHub 블로그 시작하기
├── 02. 블로그 스킨 커스터마이징
├── 03. 마크다운 글쓰기와 카테고리 관리
├── 04. SEO 최적화
├── 05. GitHub Actions 자동 배포
└── 06. 광고 및 댓글 시스템

시리즈 2: "JavaScript 핵심 개념"
├── 01. 실행 컨텍스트와 호이스팅
├── 02. 클로저 완벽 이해
├── 03. 프로토타입과 상속
└── 04. 비동기 프로그래밍

이미지 관리

기술 블로그에서 이미지는 스크린샷, 다이어그램, 아키텍처 도표 등으로 자주 사용됩니다. 효율적인 이미지 관리 방법을 알아봅시다.

로컬 이미지

가장 간단한 방법은 포스트 폴더 내에 이미지를 함께 보관하는 것입니다.

posts/my-post/
├── index.md
└── images/
    ├── screenshot-01.png
    └── architecture-diagram.png

마크다운에서 상대 경로로 참조합니다.

![스크린샷](./images/screenshot-01.png)
![아키텍처 다이어그램](./images/architecture-diagram.png)

장점: 포스트와 이미지가 함께 관리되어 직관적입니다. 단점: 리포지토리 용량이 커질 수 있습니다. GitHub 리포지토리의 권장 용량은 1GB 이하입니다.

GitHub Release 활용

리포지토리 용량을 아끼면서 이미지를 관리하는 방법입니다.

GitHub 리포지토리 > Releases > Draft a new release로 이동합니다.
이미지 파일을 드래그 앤 드롭으로 업로드합니다.
생성된 URL을 마크다운에서 사용합니다.

![스크린샷](https://github.com/username/repo/releases/download/v1.0/screenshot.png)

팁: GitHub Issues에 이미지를 드래그 앤 드롭하면 자동으로 user-images.githubusercontent.com URL이 생성됩니다. 이 URL을 복사해서 사용할 수도 있습니다.

외부 CDN 활용

이미지가 많은 블로그라면 별도의 CDN 서비스를 사용하는 것이 효율적입니다.

Cloudflare Images: 합리적인 가격, 이미지 리사이징 지원
imgbb: 무료 이미지 호스팅
GitHub 자체 CDN: Issues/PR에 이미지를 업로드하면 생성되는 URL 활용

이미지 최적화

이미지 크기가 크면 페이지 로딩 속도에 영향을 줍니다. 다음 사항을 지키면 좋습니다.

포맷: 스크린샷은 PNG, 사진은 WebP 또는 JPEG를 사용합니다.
크기: 콘텐츠 폭의 2배(Retina 대응) 정도가 적절합니다. 본문 폭이 760px이면 이미지 폭은 1520px 이하로 유지합니다.
압축: Squoosh나 TinyPNG로 압축합니다.
alt 텍스트: 접근성과 SEO를 위해 항상 의미 있는 대체 텍스트를 작성합니다.

<!-- 좋은 예 -->
![Gatsby 프로젝트 폴더 구조](./images/folder-structure.png)

<!-- 나쁜 예 -->
![](./images/image1.png)
![사진](./images/photo.png)

글쓰기 워크플로우

마지막으로, 실제 글쓰기 워크플로우를 정리합니다.

새 포스트 작성 과정

# 1. 포스트 폴더 생성
mkdir -p contents/posts/category-name/post-title

# 2. index.md 파일 생성
touch contents/posts/category-name/post-title/index.md

# 3. frontmatter 작성
# 4. 본문 작성
# 5. 개발 서버에서 확인
gatsby develop

# 6. 문제가 없으면 커밋 및 배포
git add .
git commit -m "feat: add new post - 포스트 제목"
npm run deploy

포스트 템플릿

매번 frontmatter를 처음부터 작성하는 것은 번거롭습니다. 아래 템플릿을 복사해서 사용하세요.

---
title: ""
description: ""
date: 2026-04-04
update: 2026-04-04
tags:
  -
series: ""
---

안녕하세요, **자바파커**입니다.

(도입부: 이 글에서 다루는 내용과 독자가 얻을 수 있는 것)

## 섹션 1

### 하위 섹션

## 섹션 2

## 자주 묻는 질문 (FAQ)

### Q1.

### Q2.

---

다음 포스팅에서는 ~ 다룹니다.

자주 묻는 질문 (FAQ)

Q1. 마크다운 에디터는 무엇을 추천하나요?

VS Code를 가장 추천합니다. 마크다운 프리뷰(Ctrl+Shift+V), 마크다운 린트, 이미지 붙여넣기 등 블로그 글쓰기에 필요한 확장 기능이 풍부합니다. 추천 확장 프로그램은 다음과 같습니다.

Markdown All in One: 단축키, 목차 생성, 서식 지원
Markdown Preview Enhanced: 향상된 미리보기
Paste Image: 클립보드 이미지를 바로 붙여넣기
markdownlint: 마크다운 문법 검사

Q2. 태그와 시리즈, 카테고리의 차이점은 무엇인가요?

태그(tag): 포스트의 주제나 기술을 나타내는 키워드입니다. 하나의 포스트에 여러 태그를 붙일 수 있습니다. (예: javascript, react, tutorial)
시리즈(series): 순서대로 읽어야 하는 연속 포스트를 그룹핑합니다. 하나의 포스트는 하나의 시리즈에만 속할 수 있습니다.
카테고리: gatsby-starter-hoodie에서는 폴더 구조로 카테고리를 대체합니다. 별도의 카테고리 frontmatter 필드는 없으며, 폴더 경로가 곧 카테고리 역할을 합니다.

Q3. 이전에 작성한 글을 수정하면 date도 바꿔야 하나요?

date는 최초 작성일이므로 변경하지 않습니다. 대신 update 필드를 수정일로 갱신합니다. 이렇게 하면 목록 정렬 순서는 유지되면서 독자에게 "최근 업데이트 됨"을 알릴 수 있습니다.

date: 2026-04-04    # 최초 작성일 (변경하지 않음)
update: 2026-04-10  # 수정일 (갱신)

다음 포스팅에서는 SEO 최적화 방법을 다룹니다. 검색엔진에 블로그가 잘 노출되도록 메타 태그, 사이트맵, 구글 서치 콘솔 등록까지 실전 가이드를 알아보겠습니다.