Zola로 개인 사이트를 시작하며

정적 사이트 생성기를 사용할 때 알아야 할 것

취업 이후 개인 사이트나 블로그를 운영하고 싶다는 생각은 계속 있었다. 내 이름으로 된 도메인도 구매했지만, 문제는 사이트를 구현하는것에서 발생하였다. 도무지 내가 원하는 테마가 존재하지 않았다.

여러 정적 사이트 생성기와 테마를 오가거나 바이브 코딩으로 정적 사이트를 직접 만들어본 적도 있었지만, 하지만 대부분 초기 설정 단계에서 멈췄다. 어떤 때는 스타일이 마음에 들지 않았고, 어떤 때는 구조가 만족스럽지 않았다.

결국 한동안은 HTML과 CSS로 만든 단일 페이지로 개인 사이트를 유지했다. 오히려 직접 코드를 작성하는 방식이 내 성향 상 맞는다는 생각이 들었다. 그래서 정적 사이트 생성기를 제대로 배워서 직접 운영해야만 개인 사이트를 잘 유지할 수 있겠다는 결론에 도달했다.

그 결과 선택한 도구가 Zola였고, 현재 이 사이트는 Zola로 호스팅 및 관리하고 있다. Zola를 선택한 이유는 필수적인 기능들이 내장되어 있으면서도 공식 문서가 비교적 짧아 빠르게 전체 구조를 파악할 수 있었기 때문이다. Rust로 작성되었다는 점도 마음에 들었다.
Hugo는 더 대중적이고 자료도 풍부하지만, 개인 사이트 용도로 사용하기에는 기능과 문서 규모가 다소 부담스럽게 느껴졌다.

2주정도 남는 시간을 들여서 사이트를 완성했다. 솔직히 결과물이 마음에 들지는 않는다. 하지만 내가 작성한 만큼, 충분히 시간을 들이면 좋게 바꿀 수 있다는 자신이 있다.

어느정도 zola를 사용한 입장에서 평가해보면, 현재까지는 만족스럽다.
비교군인 Hugo나 Jekyll을 깊게 사용해본 경험이 없어 직접적인 비교는 어렵지만, 내가 원하는 기능은 모두 제공하고 있고 문서도 잘 정리되어 있어 부족함은 느끼지 못했다. 특히 shortcodes가 유용해보이는데, 여러 페이지에서 공유되는 작은 컴포넌트를 재사용할 수 있다.

정적 사이트를 만들 때 알아야 할 것

정적 사이트는 어떻게 동작하는가?

AI를 활용해 개념 정리를 먼저 했다. 이 내용을 이해하고 나선, 공식 문서를 이해하는데 큰 어려움은 없었다.

GIST에 AI가 정리한 내용을 저장해두었다. (이것까지는 정리하고 싶지 않있다.)

개인적인 기준과 원칙

여러 번의 실패로 알게 된 원칙을 정리해보았다.

  • HTML / CSS / Markdown 간의 결합도를 낮춘다
    • HTML은 순수하게 구조 표현, CSS는 스타일, Markdown은 SSG 특성 상 긴 본문의 내용을 표시하는데만 집중한다.
  • JS는 사용하지 않는다. 정적 생성기에서 JS는 너무 과하고 복잡해진다.
  • 코드와 기능은 최대한 단순하게 유지한다
  • AI는 보조 도구로만 사용한다
    • 최소한 내가 이해하고 AI 없이도 수정 가능할 정도의 복잡도를 유지해야 한다

프레임워크의 기능을 사용하기

제공하는 기능을 최대한 활용한다. AI나 인터넷 글만 참고하면 이러한 부분을 놓치기 쉬우므로 공식문서를 꼭 보는걸 추천한다.

또한 컴파일 단계의 검증을 적극적으로 사용하는 편이 좋다고 생각한다. 필요한 frontmatter나 설정 값이 없을 경우 경고를 발생시키거나 빌드를 실패하게 만들 수 있는데, AI는 이런 경우를 대부분 예외 처리하려는 경향이 있다.

나는 의도적으로 이러한 예외 처리를 하지 않고, 컴파일 단계에서 실패하도록 두는 방식을 선호한다. 예를 들어 사이트 제목이나 설명 같은 메타 정보, CSS 구분을 위한 식별자 등은 항상 존재해야 하는 값이다.

HTML & 템플릿 엔진을 사용하기

가능하면 HTML 기능을 살리고 접근성을 높이려고 한다. 아직 부족한 부분이 많지만, 접근성 - MDN이나 A11y Fundamentals - Toss를 참고하고 있다.

템플릿 엔진은 정적 사이트 생성기의 핵심적인 부분은 아니지만, 기본적인 문법을 익히고 사용할 필요는 있다. HTML 주석 대신 템플릿 엔진을 사용하면 빌드 이후에 보이지 않아서 자주 사용한다.

CSS 사용하기

Zola는 Sass를 지원하지만, 개인적으로는 순수 CSS만으로도 충분하다고 판단했다. 공부해야 할 포인트를 불필요하게 늘리고 싶지 않았다. 대신 최신 CSS 기능을 적극적으로 활용하는 방향을 택했다. (관련된 글 You no longer need JavaScript)

Markdown 사용하기

Markdown은 블로그 본문처럼 텍스트 콘텐츠를 표현하는 영역에만 사용하는 것이 좋다고 생각한다.
특정 레이아웃이나 스타일을 강제하기 위한 용도로 사용하는 것은 지양하고 있다.

따라서 공유되거나 구조화된 데이터가 필요하다면 Markdown보다는 frontmatter에 두는 편이 더 적절하다. shortcodes를 사용하는 것도 좋은 방법이다.

예를 들어, 프로젝트 페이지에 프로젝트 소개 카드와 클릭 시 상세 활동 내역을 보여주는 구조라면 다음과 같이 역할을 분리할 수 있다.

  • frontmatter: 사이트 제목, 부연 설명, 메타데이터, 페이지 전역 데이터
  • shortcodes: 제목, 로고, 짧은 소개, 참여 기간을 받아 구조화된 HTML 반환
  • Markdown 본문: 상세 활동 내역과 설명

이처럼 역할을 명확히 나누는 편이 전체 구조를 이해하고 유지보수하는 데 도움이 된다.