Astro 정적 사이트로 정리한 내부 docs — 6주 회고
Notion 으로 운영하던 내부 docs 를 Astro 정적 사이트로 옮긴 6주. 그 결정의 결과.
Notion 으로 쌓이던 운영 docs 가 100페이지를 넘어가니 검색이 흐려졌다. “그 페이지 어디였더라?” 가 슬랙에 매주 나왔다.
11월 말, Astro 정적 사이트 + Markdown 으로 옮기기로 했다. 6주 운영한 결과를 정리.
옮기는 데 걸린 시간
- Astro starter 셋업: 30분
- Markdown 변환 (Notion export → mdx, 손정리): 약 4시간
- 검색 (Pagefind): 1시간
- 사이드바 (디렉토리 기반 자동 생성): 2시간
- 합 8~9시간
좋아진 것
- 검색이 빠르다: Pagefind 가 클라이언트 인덱스를 생성해서 100페이지에서도 즉시 hit. Notion 검색이 흐려지던 것과 대비됨.
- diff 가 보인다: docs 변경이 git history 로 남는다. “이거 누가 언제 바꿨지?” 가 사라졌다.
- 로컬 미리보기:
npm run dev만 띄우면 끝. 출장 비행기에서도 docs 를 본다.
안 좋아진 것
- 편집 진입장벽: 비개발자 동료가 직접 docs 를 못 고친다. PR 을 띄우거나 슬랙에 부탁해야 한다. 이건 진짜 손해.
- 이미지 처리: Notion 에선 그냥 paste 했던 스크린샷을 일일이
public/img/에 두고 경로를 적어야 한다. 마찰이 크다. - 테이블 편집: Markdown 테이블 손편집이 꽤 피곤하다. 컬럼 추가 한 번에 한 줄에 모든 cell pipe 를 다시 정렬해야 한다.
어떻게 보완했나
- 비개발자용으로는 docs 의 일부 페이지에 “수정 요청 →” 슬랙 링크를 박았다. 슬랙 → 노션 백오피스 한 페이지 → 주 1회 PR 모아서 commit. 마찰을 0 으로 만들지는 못해도 줄었다.
- 이미지는 클립보드 →
pngpasteshell alias 로 한 번에public/img/YYYY-MM-DD-<slug>.png로 저장. paste 한 줄.
다음에는 다르게 할 한 가지
내부 도구 마이그레이션은 비개발자의 사용 흐름 을 먼저 그린다. “PR 띄우면 된다” 는 답이 아니다. 그 마찰을 줄이는 보조 도구를 같이 만들지 않으면 docs 가 1인 운영으로 좁아진다.
🛒 이 글과 어울리는 추천 상품
위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.