이 사이트의 구조

이 사이트는 오래 버티도록 만들어졌다. 외부 API 호출, 데이터베이스, 사라질 수 있는 독점 도구 없이, 소스 파일만으로 전체 콘텐츠를 재빌드할 수 있어야 한다는 것이 목표다.

파이프라인

모든 페이지는 YAML 프론트매터가 있는 마크다운 파일에서 시작한다:

---
title: 내 페이지
date: 2024-01-01
tags: [예시]
---

본문 내용.

빌드 스크립트—단일 Python 파일—는 content/ 디렉토리를 순회하고, 위키링크를 해결하고, Pandoc을 호출해 마크다운을 HTML로 변환하고, 백링크를 주입하고, Jinja2 템플릿을 렌더링한 뒤, 정적 파일을 dist/에 출력한다.빌드는 결정론적이다: 같은 소스는 항상 같은 출력을 생성한다. 이는 단순한 편의가 아니라 정확성의 속성이다.

위키링크와 백링크

페이지들은 [[페이지 제목]] 문법으로 서로를 연결한다. 빌드 스크립트는 이를 컴파일 시점에 올바른 HTML 링크로 변환한다. 또한 백링크도 계산한다: 모든 페이지는 어떤 다른 페이지가 자신을 링크하는지 알고 있다.

이를 통해 사이트는 빌드 시점에 파일 시스템으로부터 조립된 그래프 구조를 가지며, 런타임 계산이 전혀 없다.

수학 표현

수학은 LaTeX로 작성되고 KaTeX로 클라이언트 측에서 렌더링된다KaTeX는 로컬에 번들링되어 있다. CDN 의존성 없음. JavaScript를 비활성화해도 HTML에는 항상 원본 LaTeX 소스가 존재한다.:

$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

인라인 수식: 오일러 항등식은 eiπ + 1 = 0.

장기 보존 보장

다음만 있으면 사이트를 재빌드할 수 있다:

  1. content/ 디렉토리 (순수 마크다운)
  2. build.py (Python 3, 표준 라이브러리 + Jinja2 + PyYAML)
  3. Pandoc 바이너리

다른 상태는 필요하지 않다. 템플릿, CSS, JS 모두 저장소에 있다. KaTeX는 ./setup.sh 실행 후 로컬에 번들링된다.

장기적 글쓰기에 대하여에서 이러한 선택의 철학을 확인할 수 있다.

역링크