Markdown 파이프라인은 방향이 둘이다. DOCX 같은 문서를 Markdown으로 옮기는 변환기, 그리고 Markdown 원고를 정적 사이트로 내보내는 출판기다. 둘 다 같은 질문에 답해야 한다. 무엇이 원본인지, 원본의 의미를 어떤 중간 표현에 담는지, 최종 산출물이 맞는지 어떻게 확인하는지다.

핵심

  • 원본은 하나만 둔다. 출판기에서는 사람이 쓰는 원고만 원본이고 sitemap, feed, 검색 데이터는 모두 다시 만들 수 있는 결과물이다. 앱이 Markdown을 직접 읽고 중간 posts.json을 두지 않으면 원고와 데이터가 어긋날 일이 사라진다. Markdown을 SSOT로 유지하는 정적 지식 출판 파이프라인
  • 의미는 문자열이 아니라 중간 표현에 담는다. DOCX는 본문, 스타일, 번호 체계, 관계 파일이 ZIP 안에 흩어진 패키지라서, 태그를 치환하는 대신 parser와 renderer 사이에 AST를 두고 문서 전체의 상태(목록 번호, 이미지 관계, 각주, 스타일 상속, 표 병합)를 해석한다. Markdown이 표현할 수 없는 서식은 fallback과 손실 정책으로 명시한다. DOCX를 Markdown으로 바꾸는 일은 왜 단순 XML 변환이 아닌가
  • 모든 산출물은 같은 변환 규칙을 공유한다. 목록, 상세 페이지, sitemap, feed가 공개 필터와 URL 규칙을 따로 구현하면 반드시 갈라지고, validator와 런타임 parser가 다르면 검사한 데이터와 배포되는 데이터가 달라진다. 같은 파서를 쓰거나 같은 fixture로 parity test를 한다. Markdown을 SSOT로 유지하는 정적 지식 출판 파이프라인
  • 공개는 opt-in이고 검증은 산출물에서 한 번 더 한다. public: true만 내보내면 표시를 빠뜨려도 공개되지 않으며, 생성된 HTML과 feed를 다시 검사하는 누출 검사는 원고 검증과 별개 단계다. 외부 API 지표는 빌드 때 캡처하되 실패해도 사이트는 계속 동작하게 한다. Markdown을 SSOT로 유지하는 정적 지식 출판 파이프라인
  • 테스트와 릴리스도 계약이다. 변환기는 unit, golden snapshot, regression, randomized invariant로 층을 나눠 검증하고, 벤치마크는 corpus와 기능 경계를 함께 밝힌다. 버전과 최소 지원 툴체인은 release manifest 하나에서 생성해 파일 간 불일치를 CI가 잡는다. DOCX를 Markdown으로 바꾸는 일은 왜 단순 XML 변환이 아닌가

관련