GitHub UI에서 Pages로, 기록을 읽기 위한 방향 전환

작성 안내
이 글은 GPTs를 활용해 블로그 원고 작성 과정의 일부를 보조받았습니다.

요약#

learning-log는 블로그에 올리기에는 가볍거나 정제되지 않은 기록들을 분리해 관리하기 위해 시작한 개인 프로젝트입니다.

작성 중심이던 GitHub 기반 기록을 읽기 중심의 정적 사이트로 전환하며, 기록을 다시 참고할 수 있는 자료로 정리했습니다.

learning-log는 메모나 코드 조각처럼 그때그때 정리하고 싶은 기록들을 남기기 위한 공간으로, 블로그에 올리기에는 가볍거나 정제되지 않은 내용들을 분리해 관리하기 위해 만든 개인 프로젝트였습니다.

빠르게 떠오른 생각이나 작업 중 남겨 두고 싶은 메모들을 곧바로 하나의 글로 다듬지 않아도 되는 형태로 기록할 장소가 필요했습니다.

이런 성격의 기록은 블로그보다는 GitHub Repository가 더 잘 맞는다고 판단했습니다.

Markdown 파일로 작성해 커밋만 하면 기록이 남았고, 처음에는 이 단순한 흐름이 learning-log의 가장 큰 장점처럼 느껴졌습니다.

하지만 기록이 쌓이기 시작하면서 다른 문제가 서서히 드러나기 시작했습니다.

기록의 양이 늘어나자 남기는 일보다 다시 읽는 일이 점점 많아졌고, 그 과정에서 GitHub UI가 글을 읽기 위한 환경으로는 불편하다는 점이 분명해졌습니다.

GitHub의 인터페이스는 코드 관리를 중심으로 설계되어 있어, 파일 단위 탐색이나 변경 이력, diff 중심의 시각은 코드에는 적합하지만 글의 흐름을 따라 읽기에는 자연스럽지 않았습니다.

Markdown 파일 하나를 읽고 나면 다음 파일로 이동할 때마다 맥락이 끊기는 느낌이 들었고, 브라우저 탐색 역시 문서를 읽는다기보다는 파일을 여닫는 경험에 가까웠습니다.

결과적으로 learning-log는 기록을 남기기에는 충분히 효율적이었지만, 쌓인 내용을 되돌아보거나 흐름을 따라 읽기에는 점점 불리한 구조가 되어갔습니다.

이 문제를 해결하기 위해 learning-log를 GitHub Pages 기반의 정적 사이트로 전환하기로 했습니다.

목표는 완성도 높은 블로그를 만드는 것이 아니라, 이미 남겨 둔 기록들을 자연스럽게 읽고 다시 찾아볼 수 있는 환경을 만드는 것이었습니다.

그래서 입력 방식은 그대로 두고, 출력만 바꾸는 방향을 선택했습니다.

Markdown 파일은 기존과 동일하게 유지하고, 이를 HTML로 변환해 docs 디렉터리 아래에 정적 페이지로 생성하도록 구성했습니다.

Node.js와 몇 가지 npm 패키지를 사용해 간단한 빌드 과정을 만들었고, Markdown을 읽어 FrontMatter와 본문을 분리한 뒤 템플릿에 렌더링하고 검색을 위한 인덱스를 생성하도록 설정했습니다.

기술적으로는 복잡한 작업은 아니었지만, 이 시점부터 기록을 바라보는 기준은 조금씩 달라지기 시작했습니다.

Pages로 전환한 이후 기록을 대하는 감각은 확실히 달라졌습니다.

문서를 열었을 때 글의 흐름이 끊기지 않고 이어졌고, 코드 블록과 본문 역시 브라우저에서 읽기 좋은 형태로 렌더링되었습니다.

링크를 통해 문서 간 이동이 가능해지면서 개별 파일을 여는 느낌보다는 하나의 기록 묶음을 탐색하는 감각이 생겼습니다.

검색 기능이 추가되자 예전에 남겨 둔 코드나 메모를 다시 찾는 일도 훨씬 수월해졌습니다.

GitHub UI에서 파일을 연다는 인상이 강했던 learning-log는 이제는 전체를 하나의 작은 사이트처럼 훑어볼 수 있는 기록 공간에 가까워졌습니다.

이번 전환을 거치며 다시 느낀 점은 기록에서 중요한 것은 어떻게 남길까보다 어떻게 다시 읽을 수 있을까에 더 가깝다는 사실이었습니다.

기술적으로는 단순한 정적 사이트 전환이었지만, 기록을 대하는 태도는 분명히 달라졌습니다.

이전까지 learning-log는 코드 조각이나 짧은 메모를 저장하는 공간에 가까웠다면, Pages로 옮긴 이후에는 다시 찾아 읽고 참고할 수 있는 자료로 성격이 바뀌기 시작했습니다.

이 구분이 생긴 뒤로는 어떤 내용을 어디에 남길지에 대한 판단도 훨씬 명확해졌습니다.

기록은 완성된 결과물이 아니라, 나중에 다시 돌아와 맥락을 이어가기 위한 흔적으로 남게 되었습니다.