블로그를 처음 만들 때는 게시글 파일을 한 폴더에 쭉 넣는 방식이 가장 단순합니다.

예를 들어 이런 구조입니다.

content/posts/
  html-first-document.md
  spring-boot-start-from-download.md
  pair-function.md

처음에는 이 구조가 편합니다.

파일 하나가 글 하나이고, 어디에 저장되는지도 바로 보입니다.

하지만 글이 점점 많아지면 생각보다 빨리 불편해집니다.

이번 글에서는 제가 왜 flat 구조를 버리고, 글 하나당 폴더 하나를 가지는 구조로 바꾸게 되었는지 정리해보겠습니다.

처음에는 왜 flat 구조가 편했을까?

처음 글 수가 적을 때는 content/posts 아래에 마크다운 파일을 바로 두는 방식이 이해하기 쉽습니다.

content/posts/
  hello-world.md
  html-css-javascript-differences.md
  spring-boot-crud-api-basic.md

이 구조의 장점은 분명합니다.

  • 파일을 찾기 쉽습니다.
  • 로더를 단순하게 만들 수 있습니다.
  • 마크다운 글만 운영할 때는 빠르게 시작할 수 있습니다.

즉, 블로그를 처음 만들고 글이 몇 개 없을 때는 flat 구조가 오히려 자연스럽습니다.

글이 많아지면 어떤 문제가 생길까?

글 수가 늘어나면 한 폴더 안에 HTML, Spring Boot, 알고리즘, SQL 글이 전부 섞이게 됩니다.

예를 들어 이런 느낌이 됩니다.

content/posts/
  html-first-document.md
  html-links-and-images.md
  spring-boot-first-jpa-member.md
  spring-boot-crud-api-basic.md
  pair-function.md
  xor-linked-list.md
  sql-top-sales-by-category.md

이 상태가 되면 다음 문제가 생깁니다.

1. 파일을 찾는 데 시간이 걸린다

카테고리별로 분리되어 있지 않기 때문에, HTML 글만 보고 싶어도 파일명을 눈으로 훑어야 합니다.

Spring Boot 글이 많아지면 spring-boot-로 시작하는 파일이 몰리고, 알고리즘 글까지 섞이면 폴더가 금방 복잡해집니다.

2. 이미지까지 붙기 시작하면 더 지저분해진다

나중에 게시글에 이미지를 넣으려면 이런 고민이 생깁니다.

이 이미지가 어떤 글에 쓰인 파일이지?
본문 이미지와 썸네일을 어디에 둘까?

글은 content/posts에 있고, 이미지는 public에 따로 흩어져 있으면 관리 포인트가 두 군데로 나뉩니다.

3. 글 하나를 옮기거나 복사할 때 관련 파일을 함께 챙기기 어렵다

글 본문, 커버 이미지, 예시 이미지, 썸네일이 서로 다른 곳에 있으면 글 하나를 묶어서 다루기 어렵습니다.

즉, 글 수가 적을 때는 단순함이 장점이지만, 운영 기간이 길어질수록 같은 구조가 관리 비용으로 돌아옵니다.

특히 이미지 계획이 있으면 더 빨리 바꿔야 한다

제가 폴더 구조를 고민한 가장 큰 이유도 여기에 있었습니다.

나중에는 글에 이런 것들이 붙을 가능성이 높습니다.

  • 본문 설명 이미지
  • 예시 화면 캡처
  • 썸네일
  • 대표 이미지

이때 글 파일은 여기 있고

content/posts/html-first-document.md

이미지는 여기 있으면

public/posts/html-first-document/cover.png
public/posts/html-first-document/example-1.png

논리적으로는 연결되지만, 물리적으로는 한곳에 있지 않습니다.

처음에는 괜찮아 보여도, 글이 많아질수록 "이 글과 관련된 파일이 어디 있지?"를 자주 찾게 됩니다.

그래서 이미지 운영까지 생각한다면 flat 구조를 너무 오래 유지하지 않는 편이 좋다고 판단했습니다.

어떤 구조를 선택했을까?

최종적으로는 이런 구조가 가장 관리하기 좋다고 봤습니다.

content/posts/
  html/
    html-first-document/
      index.md
  spring-boot/
    spring-boot-crud-api-basic/
      index.md
  algorithm/
    pair-function/
      index.md

즉 기준은 다음과 같습니다.

content/posts/<category-folder>/<post-slug>/index.md

이 구조의 핵심은 "글 하나 = 폴더 하나"입니다.

이 구조가 좋은 이유

1. 카테고리별로 먼저 나뉜다

HTML 글은 html, Spring Boot 글은 spring-boot, 알고리즘 글은 algorithm 아래로 들어갑니다.

그래서 파일 탐색기에서 카테고리 단위로 먼저 시야를 줄일 수 있습니다.

2. 글 하나와 관련 파일을 한곳에 모을 수 있다

예를 들어 나중에 이미지까지 붙이면 이렇게 갈 수 있습니다.

content/posts/html/html-links-and-images/
  index.md
  cover.png
  example-link.png
  example-image.png

이러면 글과 관련된 자산이 한 폴더에 모입니다.

3. 나중에 썸네일, OG 이미지, 예시 파일을 붙이기 쉽다

지금은 마크다운 파일만 있어도, 나중에 같은 폴더에 이미지를 추가하면 됩니다.

구조를 다시 뜯지 않아도 되기 때문에 확장성이 좋습니다.

4. 글 하나를 이동하거나 백업하기가 쉽다

글 폴더 하나만 보면 해당 글의 본문과 관련 자산을 같이 다룰 수 있습니다.

즉, 운영 관점에서 훨씬 덜 헷갈립니다.

바꾸면서 같이 손봐야 했던 부분

폴더 구조만 바꾸고 끝나는 것은 아니었습니다.

기존 로더가 이런 방식만 가정하고 있었다면:

content/posts/*.md

이제는 재귀적으로 폴더를 읽어야 합니다.

즉, 블로그 코드도 함께 바뀌어야 합니다.

필요했던 작업은 대략 다음과 같습니다.

  • content/posts 아래를 재귀적으로 탐색하기
  • index.md를 실제 게시글 파일로 인식하기
  • 폴더 이름을 slug로 사용하기
  • 기존 URL은 유지되게 만들기
  • 중복 slug가 없는지 체크하기

즉, 파일 구조 리팩터링은 단순히 파일을 옮기는 작업이 아니라, 콘텐츠 로더와 운영 규칙까지 같이 정리하는 작업이었습니다.

flat 구조가 완전히 나쁜 건 아니다

중요한 점은 flat 구조가 틀렸다는 뜻은 아니라는 것입니다.

다음 조건이라면 flat 구조도 충분히 괜찮습니다.

  • 글 수가 아직 적다
  • 이미지를 거의 쓰지 않는다
  • 카테고리 수가 많지 않다
  • 빠르게 시작하는 것이 더 중요하다

즉, 블로그 초반에는 flat 구조가 좋은 선택일 수 있습니다.

다만 글이 쌓이고 이미지까지 붙기 시작하면, 언젠가는 리팩터링 비용이 생길 가능성이 큽니다.

언제 폴더형 구조로 바꾸는 게 좋을까?

제 기준에서는 아래 신호가 보이면 바꾸는 것이 좋습니다.

  • 한 폴더에서 글 찾기가 번거롭다
  • 카테고리가 여러 개로 나뉜다
  • 시리즈 글이 많아진다
  • 이미지나 썸네일을 넣을 계획이 있다
  • 글 하나와 관련 파일을 같이 관리하고 싶다

이 단계가 오면 미루기보다 한 번 구조를 정리하는 것이 오히려 편합니다.

정리

블로그 글 구조를 flat에서 폴더형으로 바꾼 이유는 단순합니다.

처음에는 flat 구조가 빠르고 단순했지만, 글 수가 늘고 이미지 계획까지 생기면서 관리 비용이 커졌기 때문입니다.

결국 제가 선택한 방향은 다음과 같습니다.

카테고리로 먼저 나누고,
글 하나당 폴더 하나를 만들고,
본문과 관련 자산을 한곳에 모은다.

이 구조는 처음에는 조금 손이 가더라도, 이후 운영과 확장에서는 훨씬 편합니다.

특히 이미지까지 같이 관리하고 싶다면, flat 구조보다 폴더형 구조가 더 오래 버티는 선택이라고 생각합니다.