Step 4. 구현 - 마크다운 형식 설계하기

들어가며

디자인이 끝난 다음 코드를 구현을 시작합니다. 1편에서 쪼개놓은 질문 목록 중 답을 못 낸 것들이 몇 개 남아 있었고, 코드를 쓰면서 하나씩 정했습니다.

1. 미뤄둔 질문에 답하기

카테고리 - 2단까지, 주소는 한 겹

플랫로 갈지 서브카테고리까지 둘지 정하지 못했습니다. 2단까지 두되 주소는 한 겹으로 가기로 했습니다.

주소는 /category/java-concurrency 처럼 한 계층입니다. /category/java/concurrency 같은 중첩 경로를 만들지 않습니다.

검색 - 서버 없이

검색 서버를 붙일지 클라이언트에서 끝낼지도 미뤄뒀던 질문입니다. 글 수를 생각하면 클라이언트에서 처리하는게 효율적이라고 판단하였습니다.

전체 글의 제목, 요약, 태그, 카테고리를 페이지를 만들 때 같이 내려주고 필터링은 브라우저에서 합니다. 검색 인덱스 서비스도 검색 API도 없습니다. ⌘K 로 여는 커맨드 팔레트도 같은 데이터를 씁니다.

글이 몇천 편이 되면 다시 봐야 할 결정이지만 그때 가서 바꾸면 됩니다.

2. 마크다운 문법을 직접 정의한 이유

마크다운 문법을 재정의하였습니다. 추후 이식성 관점에서 본다면, 리스크가 큰 결정이었다고 생각합니다. 하지만, 기존 마크다운 문법을 확장하여 INFO, WARN과 같은 callout 태그, 링크 카드 등 가독성 좋은 블로그 포스팅에 유용한 컴포넌트와 편의성을 챙길 수 있었습니다. 특히 순정 마크다운에서 콜아웃의 내부 줄바꿈이나 내부 wrapper 문법 선언 안됨 등.. 불편한게 너무너무 많았던 점이 컸습니다.

확장 문법 중 콜아웃 컴포넌트를 예로들면 아래와 같이 태그를 > [!] 형태로 선언하면, 줄바꿈 시 자동으로 '>' 가 따라오는 구조입니다.

1> [!NOTE] NOTE 제목
2> 본문 내용
3
4> [!WARNING] WARNING 제목
5> 본문 내용
6
7> [!TIP] TIP 제목
8> 본문 내용
9
10> [!INFO] INFO 제목
11> AAA
12> BBB
13> CCC

실제 렌더된 callout

src/lib/markdown.tsx 에 파서 한 벌을 만들어 Studio 미리보기와 글 상세가 그걸 같이 쓰게 했습니다. 보면서 쓴 화면과 발행된 화면이 같은 코드로 렌더됩니다. 이 마크다운 문법/렌더 또한 정본 관리를 위해 문서를 작성하였는데 아래에서 다룹니다.

문법을 일부러 좁혔습니다

꼭 필요한 문법외에 나머지는 덜어내었습니다.

문법보다 문서를 유지합니다

claude.ai↗

Claude Artifact

Try out Artifacts created by Claude users

문법을 좁힌 대신 문서를 한 장으로 유지하고 있습니다. MARKDOWN.md 에 쓸 수 있는 표기를 전부 적고, 안 되는 표기도 왜 안 되는지와 안 지켰을 때 화면에 어떻게 나오는지까지 같이 적어뒀습니다.

파서를 고치면 이 문서부터 고칩니다. 문법이 늘어나는 건 언제든 할 수 있지만, 문서에 없는 문법이 코드에만 생기면 그때부터 글 쓸 때마다 파서를 읽어야 합니다.

3. 시리즈 탭 신설

지금 읽고 계신 이 글도 시리즈의 한 편입니다. 하나의 시리즈는 블로그와 같이 하나의 목표를 묶어서 보기 쉽도록합니다. 먼저 주제와 편수를 선언하고, 다음편을 연재하는 방식입니다. 방문자 입장에서 관심있는 글을 쉽게 고를 수 있는 재밌는 기능이라고 생각합니다.

4. 에디터 구현

에디터는 운영하는 입장에서 가장 많이 사용하는 화면이므로 편의성을 가장 중점적으로 두었습니다.

• 기본적으로는 마크다운 문법과 동일하게 작동하게 (리스트 입력 중 엔터 시 - 자동생성, 엔터 한번 더 클릭 시 사라짐과 같은 친화적 플로우 이식)
• 이미지 업로드 — 드래그, 붙여넣기, 툴바 세 가지 경로를 모두 받습니다
• 마우스 없이 마크다운 문법만으로 글을 완성할 수 있게, 단 마크다운 문법 힌트나 버튼은 제공

• 글 관리 — published / private / review / draft 로 글을 상태별로 관리

5. 티스토리 마이그레이션

티스토리 글을 전체 백업 후 마이그레이션 스크립트를 작성하여 사용하였습니다.

• 티스토리 백업 XML 파싱 (fast-xml-parser)
• HTML을 현재 규칙의 마크다운으로 변환 (turndown)
• 인라인 이미지 다운로드 후 글별 폴더로 정리
• 제목, 요약, 카테고리, 태그, 날짜 자동 생성

이후 변환 결과가 평문 마크다운이라 눈으로 읽으면서 검수할 수 있었습니다. HTML 그대로 옮겼다면 렌더 전까지 검수하기에 어려움이 있었을겁니다.

닫으며

구현 단계에서도 결정과 문서작업을 주로 하였습니다. 특히 받지 않기로 한 문법, 만들지 않기로 한 검색 서버, 중첩하지 않기로 한 주소 등 제약을 구체화하였습니다. 추가적인 기능은 나중에도 붙일 수 있지만 제약은 초반에 정하지 않으면 더 큰 변경이 필요합니다.

다음 단계는 검증과 배포입니다.