Notion API를 이용한 정적 웹 페이지 제작기 - 2편

회사 프론트로는 Alpine.js 를 사용하고 있었지만, 백엔드로는 python 의 django 를 사용하고 있었고, 각종 개발 문서를 관리하기 위해 sphinx 를 사용할 준비를 하고 있었다.

그래서, 차라리 이런 FAQ 페이지나, How to Use 페이지는 정적으로 관리하는 편이 나아보였다. 그리고 추후 다른 개발 문서와의 통합을 위해 시범적으로 sphinx 를 사용해보는 방향으로 진행하게 되었다.

회사에서 제공하는 서비스는 해당 분야의 전공자(계산화학, 생명공학)가 아니면 이해하기 힘들 정도로 domain-specific 한 분야였다. 또한, 아직 서비스 모듈들이 완벽하게 개발된 것이 아니었기 때문에 그 내용(튜토리얼, 사용법 등)이 수시로 바뀔 수 있었다.

그래서 회사 내의 사이언티스트 분들과 모듈 개발자들이 수시로 FAQ, How to Use 문서를 수정할 수 있어야 했다.

몇 번의 회의 끝에, 회사 노션에 내용을 작성하는 것이 가장 효율적이라고 판단했다.

따라서, 노션에 작성한 내용을 정적 페이지로 제공하기 위해 다음과 같은 파이프라인을 구상하였다.

pipeline

1. 노션 페이지 데이터 요청
2. 노션 블록 데이터를 가져옴
3. 받아온 블록 데이터를 markdown 형식으로 변환
4. markdown 후처리
5. 처리된 markdown 파일을 pandoc의 입력으로 pipe
6. pandoc 을 이용해서 markdown 을 rst(reStructedText) 포맷으로 변환 및 저장
7. sphinx 가 저장된 rst 파일을 이용해서 정적 페이지 생성
8. 배포

이러한 작업을 매 배포시 실행되게 하기 위해 배포 스크립트에 포함하였고, 항상 최신(정확히는 배포 당시)의 데이터가 반영되도록 하였다.

과정을 세밀하게 적어서 복잡해보이지만, 이전 방식에 비해 훨씬 간단하고 직관적인 방법이 되었다. 통일성을 위해 sphinx 를 이용하다보니 중간에 rst 로 변환하는 과정이 들어갔지만, 전체적으로 보면 노션 → 마크다운 → rst → html 인 느낌이다.

(위 파이프라인의 4. markdown 후처리 부분에 해당)

한 페이지 내에 여러 이미지를 넣고, 그 이미지를 원하는대로 배치하고 싶다는 팀원의 요청이 있었다. 일반적으로 마크다운에서는 inline html 을 쓰지 않는 이상 이미지의 위치를 지정하는 것이 힘들기 때문에 고민이 많았다.

논의 끝에 노션 이미지의 캡션을 사용하는 것이 어떨까 하는 의견이 나왔고, 분수 꼴로 캡션을 작성하면 그것 기반으로 이미지의 위치를 지정해주는 방식으로 차차 방향을 잡아나갔다.

당시 작성한 사내 노션 문서. (모든 사내 공식문서는 영어로 작성해야 했다)

이미지의 위치를 지정해줄 캡션과 실제 캡션을 모두 쓸 수 있도록 했으며, 1, 2, 4 등분으로 배치할 수 있도록 했다.

결과만 놓고 보면, 다소 길을 돌아온 느낌이었다.

처음에는 Alpine.js 에서 동적으로 불러오는 방법으로, 이후에는 sphinx 를 이용해서 정적으로 서브하는 방법으로 하는 등의 다양한 방법으로 페이지를 만들어보니 나름대로 웹에 대한 이해도가 약간은 높아진 것 같았다.

특히나 이렇게 markdown 을 이용해서 정적인 페이지를 만든 경험은 본 블로그를 만드는 데에도 큰 도움을 주었다. 이미지나 헤더, 토글 등을 후처리 하는 과정도 꽤나 도움이 되었던 것 같다.

지금 보면 개선점이 참 많아보이지만, 그 당시에 할 수 있었던 최선을 다했다고 생각한다!