🧠 기술 문서의 '기술 부채(Tech Debt)'를 청산하는 제로 설정 아키텍처
소프트웨어 엔지니어링에서 코드를 작성하는 것만큼이나 중요한 것이 문서화(Documentation)입니다. 하지만 많은 조직에서 문서는 코드베이스의 발전 속도를 따라가지 못하고 레거시로 전락합니다. 문서 도메인을 세팅하고, CSS를 만지고, 라우팅을 구성하는 '인프라 작업'이 개발자의 생산성(Velocity)을 갉아먹는 병목(Bottleneck)이 되기 때문입니다.
최근 급부상하는 docmd를 비롯한 모던 SSG(정적 사이트 제너레이터)들은 이 문제를 아키텍처 레벨에서 해결합니다. 개발자는 오직 마크다운(Markdown) 작성에만 집중하면, 시스템이 CI/CD 파이프라인을 타고 자동으로 다크 모드, 구문 하이라이팅, SEO가 완벽하게 적용된 산출물을 렌더링합니다.
단순한 블로그를 넘어, 제품의 API 명세서나 사내 위키를 구축할 때 시스템 리소스를 최소화할 수 있는 최적의 도구들을 소개합니다.
🛠️ 레퍼런스 가이드: 3-Step 문서화 파이프라인 구축 (docmd 기준)
Node.js 환경이 세팅된 로컬 PC에서, 단 3개의 터미널 명령어만으로 제로 설정(Zero-config) 문서 웹사이트를 컴파일하고 구동하는 파이프라인입니다.
Step 1. 시스템 스캐폴딩 (Initialization)
프로젝트 폴더를 생성하고 npx를 통해 기본 구조와 필수 패키지를 한 번에 내려받습니다.
mkdir devbj-docs && cd devbj-docs
npx docmd init
Step 2. 마크다운 원시 데이터(Raw Data) 주입
복잡한 라우팅 설정 없이, 생성된 docs 디렉토리 안에 마크다운 파일(.md)을 던져 넣기만 하면 시스템이 파일명을 기준으로 알아서 좌측 사이드바와 목차(TOC)를 생성합니다.
echo "# 파이프라인 개요\n이곳에 기술 문서를 작성합니다." > docs/architecture.md
Step 3. 정적 에셋 컴파일 및 로컬 서버 구동 (Build & Serve)
주입된 마크다운을 팁 박스, 다크 모드, 구문 하이라이팅이 완벽히 적용된 정적 HTML/CSS 파일로 렌더링(컴파일)하여 즉시 확인합니다.
npm run dev
# 프로덕션 배포 시 빌드 명령어: npm run build
단 1분 만에 localhost 환경에서 완벽한 문서 사이트가 구동됩니다. 이제 이 코드를 GitHub에 푸시(Push)하고 Cloudflare Pages나 Vercel에 연동해 두면, 마크다운 파일을 수정할 때마다 자동으로 전 세계 서버에 배포되는 문서화 CI/CD 자동화가 완성됩니다.
💡 FAQ: 문서화 웹사이트 구축 트러블슈팅
Q. 일반 Markdown(MD)과 MDX의 차이는 무엇인가요?
A. 일반 MD가 정적인 텍스트와 이미지 포맷팅만 지원한다면, MDX는 마크다운 문서 내부에 React나 Vue, Astro 등의 대화형 UI 컴포넌트(버튼, 차트, 계산기 등)를 직접 Import하여 렌더링할 수 있는 확장 포맷입니다. Docusaurus나 Starlight 같은 최신 SSG는 대부분 MDX를 기본 지원합니다.
Q. 정적 사이트(SSG)는 DB가 없는데 전체 검색 기능은 어떻게 구현하나요?
A. 자체적인 검색 백엔드를 구축할 필요가 없습니다. 문서화 생태계에서는 Algolia DocSearch를 연동하는 것이 글로벌 표준입니다. Algolia의 크롤러가 주기적으로 내 문서 사이트를 스크래핑하여 검색 인덱스를 만들어주며, 프론트엔드에서는 제공되는 API 키만 입력하면 0.1초 만에 반응하는 초고속 검색창이 완성됩니다.
Q. 이렇게 만든 문서 사이트를 무료로 호스팅할 수 있나요?
A. 네, 서버 유지비는 0원입니다. GitHub 저장소에 마크다운 파일을 푸시(Push)하기만 하면, GitHub Actions가 이를 감지하여 Cloudflare Pages, Vercel, Netlify, 또는 GitHub Pages의 글로벌 CDN 엣지(Edge) 네트워크로 자동 빌드 및 배포해 줍니다. 백엔드 서버가 없으므로 트래픽 요금 폭탄에서도 자유롭습니다.