기술 블로그 운영하면서 느낀 Markdown 팁 & 관리 전략

내 프로젝트와 문제 해결 과정을 기록하면서, 마크다운과 기술 블로그 관리에 대해 체득한 실제 경험을 정리한다.

🛠 시작은 단순한 기록에서

기술 블로그를 처음 시작했을 때는 단순한 기능 공유 정도였다.
“이 문제 해결했는데, 다음에 또 생기면 까먹을 것 같아…”
그런 마음으로 Notion이나 Word에 적던 내용을 Jekyll 블로그에 옮기기 시작했다.

😵‍💫 예상치 못한 어려움들

프로젝트 중간중간 마주한 이슈들이 있었다. 예를 들어:

💡 사례 1: ISR 적용했는데 왜 캐시가 안 바뀌지?

• 문제: Next.js ISR을 적용했는데 실제 배포 페이지가 업데이트되지 않음
• 원인: revalidate 시간이 너무 길게 설정되어 있었고, getStaticProps도 캐시 재활용 중
• 해결: fetch 요청을 Edge function으로 변경하고, no-store 헤더로 캐시 무효화

💡 사례 2: Gboard가 안 나오는 안드로이드 에뮬레이터

• 문제: 하드웨어 키보드만 뜨고, Gboard는 회색으로 비활성화
• 해결: adb shell settings put secure show_ime_with_hard_keyboard 1 설정 후 재부팅

💡 사례 3: JEUS 서버에서만 JSON 응답이 이상하게 나옴

• 문제: 특정 컨트롤러만 응답 JSON 객체가 두 번 출력됨
• 원인: JSP 내부에서 JSON을 직접 출력하고, 컨트롤러에서도 반환하고 있었음
• 해결: 응답처리를 한 곳으로 통일하고 필터/인터셉터 점검

이러한 문제를 해결하고 정리하는 과정에서, 마크다운 파일을 관리하는 노하우도 쌓이기 시작했다.

✍️ 마크다운 작성 실전 팁

✅ 1. 코드블럭 안에는 줄임 없이!

```javascript // ❌ 이건 다음에 봐도 모름 app.lookup(“grpForm”).style.css({ /* transition 설정 */ });

// ✅ 이렇게 정확히 써줘야 다시 봐도 이해됨 app.lookup(“grpForm”).style.css({ “transition”: “width 0.5s ease, height 0.5s ease” }); ```

✅ 2. 이미지와 캡처는 /assets/images/YYYY-MM-DD 식으로 관리

• 캡처 이미지가 많아질수록 폴더를 날짜 기준으로 정리
• .md 파일 안에서는 상대경로로 참조

✅ 3. 오류 해결 경험은 📌 문제, ✅ 해결, 🚨 주의사항 섹션으로 분리

``` 📌 문제: 모바일에서 영상이 느리게 로딩됨 ✅ 해결: .webm 포맷 사용 + preload=“auto” 🚨 주의사항: 모바일 네트워크 환경에 따라 autoplay 막힐 수 있음 ```

📁 기술 블로그 관리 전략

🔄 1. 글 초안은 /drafts 폴더에

• 정기적으로 drafts 폴더를 posts로 이동하며 리뷰

🧠 2. 주제별 태그 및 시리즈화

• 예: #vercel, #figma-to-code, #nextjs
• 관련 글을 묶어 시리즈 단위로 구성하면 재방문율 상승

📦 3. Git으로 .md 버전 관리

• 마크다운도 소스처럼 관리하면, 예전 글도 안전하게 수정 가능

🔌 추천 마크다운 확장 및 도구

• Typora: 실시간 프리뷰용 마크다운 에디터
• VSCode + Markdown All in One: 자동 번호 매기기, TOC 삽입 등
• Jekyll plugins
  • jekyll-toc: 자동 목차
  • jekyll-seo-tag: SEO 태그 자동 생성

🧭 마무리하며

프로젝트의 경험을 단순히 “기억”에만 맡기기엔 너무 아깝다.
마크다운은 그 경험을 구조화하고, 공유 가능하게 만들어주는 최적의 포맷 이다.

앞으로도 내가 겪은 문제들, 해결 방법, 그리고 그 과정에서 생긴 깨달음들을 글로 정리하면서,
더 좋은 개발자이자 기록자가 되기를 바란다.

“기록하지 않은 코드는, 하지 않은 것과 같다.”