렌더링 시간 단축 가이드 (freeze & 렌더 전략)

chadchae.github.io 렌더 속도를 줄이는 방법. 최종 갱신: 2026-06-30

0. 먼저 알아야 할 핵심: freeze가 무엇을 캐시하는가

freeze는 “코드 실행(execute) 결과”만 캐시한다. 마크다운→HTML/PDF 변환(pandoc)은 캐시하지 않는다.

진단 결과 이 사이트의 모든 포스트는 실행 코드청크(```{r}, ```{python})가 0개다(순수 텍스트). 따라서:

⚠️ 현재 이 블로그에서 freeze는 렌더 시간을 거의 줄이지 못한다. 캐시할 “코드 실행”이 없기 때문이다. 느린 원인은 freeze가 아니라 (1) 멀티 포맷(PDF) 변환 + (2) 전체 사이트 일괄 렌더다.

freeze: true는 무해하니 그대로 둬도 되지만, 속도의 진짜 레버는 §2다.

1. freeze 올바른 사용법 (코드 있는 글이 생길 때)

향후 R/Python 분석 코드를 포함한 글을 쓰면 그때 freeze가 효력을 갖는다.

설정	의미	권장
`freeze: true`	항상 캐시 사용(소스 바뀌어도 재실행 안 함)	결과 고정용
`freeze: auto`	소스가 바뀔 때만 재실행	✅ 일반 권장
`freeze: false`	매번 재실행	디버깅용

프로젝트 기본값은 _quarto.yml의 execute: freeze: true. 개별 글 front-matter로 덮어쓸 수 있다.
코드 글이 생기면 freeze: auto가 안전하다(바뀐 글만 다시 실행).

# 코드 분석 글 front-matter 예
execute:
  freeze: auto      # 소스 변경 시에만 재실행

재현성 주의: 캐시는 _freeze/에 저장된다. 이 레포는 .gitignore가 소스를 전부 무시(=_freeze 비추적)하므로 캐시는 로컬 전용이다. 다른 PC에선 첫 렌더 때 다시 실행된다(코드 글이 있을 때만 의미).

2. 진짜 속도 레버 (이 블로그에 효과 큰 순서)

① 변경된 글만 렌더 (가장 효과 큼)

전체 사이트(quarto render)는 ~49개 문서를 모두 다시 만든다. 바뀐 글 1개만 렌더하면 수십 배 빠르다.

quarto render "posts_kr/2026-06-29-보이는것은-키우고-사람은-줄인다/보이는것은-키우고-사람은-줄인다.qmd"

→ 해당 글 + 연결된 리스팅 페이지만 갱신된다.

② 초안 중엔 HTML만 렌더

PDF(LaTeX)·docx 변환이 가장 느리다. 작성·확인 단계에선 HTML만:

quarto render "<글>.qmd" --to html

주의: 전체 사이트에 --to html을 쓰면 기존 docx/pdf가 정리(삭제)될 수 있다. --to html은 단일 글 렌더에만 사용하라.

③ 포맷 다이어트 (구조적 최대 절감)

지금 포스트는 html + docx + pdf 3종을 선언한다. PDF는 kotex/LaTeX로 글 하나당 수 초~수십 초가 든다. 블로그가 HTML만 필요하면 front-matter에서 docx/pdf를 빼라:

format:
  html:
    toc: true
    # docx, pdf 블록 삭제 → PDF/LaTeX 비용 0

→ 다운로드 버튼(docx/pdf)이 필요 없다면 이 한 가지가 전체 렌더 시간을 가장 크게 줄인다.

④ 프리뷰 데몬과 충돌 금지

에디터의 quarto preview가 떠 있으면 별도 quarto render와 충돌해 파일이 꼬인다. 렌더 전 종료:

pkill -f "quarto.*preview"

3. 권장 워크플로

상황	명령	비고
글 1편 작성·수정	`quarto render "<글>.qmd" --to html`	빠름, HTML만
글 1편 최종(다운로드 포함)	`quarto render "<글>.qmd"`	그 글만 전체 포맷
사이트 전체 갱신(배포 직전)	`pkill -f "quarto.*preview"` 후 `quarto render`	데몬 끄고 1회

배포: quarto render → git add docs → commit → git push origin main.

4. 한 줄 요약

이 블로그는 코드가 없어 freeze로는 안 빨라진다. 진짜 단축법은 ① 바뀐 글만 렌더, ② 초안 땐 --to html, ③ 필요 없으면 docx/pdf 포맷 제거(LaTeX 비용 삭제). freeze는 향후 코드 분석 글에서 auto로 쓸 때 의미가 있다.