DocFX 빌드 시점에 원격 Markdown 통합 및 페이지 단위 Governance 체계 구축

docfx-remote-include: inline remote markdown into DocFX, and govern the assembled page

sai pramod upadhyayula2026년 6월 9일5분intermediate

AI 요약

Context

정적 문서 생성 도구인 DocFX의 로컬 파일 의존성을 해결하여 분산된 콘텐츠의 중앙 집중 관리가 필요함. 기존의 파편화된 AI 리라이트 방식은 관리 복잡도가 높아 전체 페이지 단위의 일관된 거버넌스 적용 구조가 요구됨.

Technical Solution

Markdig extension 기반의 !remoteinclude 지시어를 도입하여 빌드 타임에 HTTP 서비스로부터 Markdown 콘텐츠를 동적으로 fetch 및 인라인화하는 구조 설계
AsyncLocal 기반의 소스 스택을 활용한 최대 8단계의 Cycle Detection 및 In-process 캐싱을 통한 빌드 성능 최적화
동시성 제어를 위해 In-flight request를 8개로 제한하여 외부 콘텐츠 서비스의 부하를 방지하는 Throttling 메커니즘 적용
YAML Frontmatter의 메타데이터와 조립된 전체 페이지를 IPageTransformService로 전송하여 LLM 기반의 톤앤매너 조정 및 중앙 가이드라인 준수 여부를 검증하는 Page-level Transform 프로세스 구축
Kubernetes 환경에서 knowledge-service를 Sidecar 패턴으로 배치하여 빌드 컨테이너와 localhost 통신을 통한 네트워크 지연 최소화 및 보안 강화

실천 포인트

- 외부 리소스 fetch 시 무한 루프 방지를 위한 Depth 제한 및 Cycle Detection 로직 구현 검토 - 개별 컴포넌트 단위의 수정보다 최종 조립된 결과물을 한 번에 처리하는 'Page-level Transform' 방식의 단순성 확보 - 민감 정보 유출 방지를 위해 설정 파일이 아닌 환경 변수나 콜백 기반의 인증 메커니즘 채택

태그

#Sidecar Pattern #Content-as-Code #Markdig #Governance #DocFX

원문 읽기