Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

원문 렌더가 준비되기 전까지 텍스트 가이드로 표시합니다.

프롤로그 — SSG는 죽지 않았다, 다시 정의됐다

2026년 봄, 누군가 트위터에 "SSG는 끝났다, 모두 Next.js Server Components로 옮겨갔다"라고 썼다. 그 트윗은 1만 명에게 도달했고 9천 명이 동의하지 않았다. 진짜 풍경은 정반대다. 정적 사이트 생성기 — Static Site Generator, 줄여서 SSG — 는 지난 5년간 죽기는커녕 두 갈래로 갈라져 더 강해졌다.

한쪽은 **콘텐츠 사이트**다. 회사 블로그, 마케팅 사이트, 개인 포트폴리오, 뉴스레터 아카이브. Hugo가 Go의 속도로 1천 페이지를 몇 초에 빌드하고, Eleventy 3가 자바스크립트 진영의 단순함을 다시 정의했고, Astro가 "콘텐츠 우선"이라는 카테고리 자체를 만들었다. 이쪽은 SEO, 페이지 속도, RSS, 다국어, 마크다운 워크플로가 핵심이다.

다른 한쪽은 **문서 사이트**다. OSS 라이브러리 문서, SaaS API 레퍼런스, 회사 내부 위키, 변경 로그. MkDocs Material이 파이썬 진영의 사실상 표준이 됐고, Docusaurus가 메타(Meta)의 React+MDX 조합으로 십수만 OSS 프로젝트의 문서를 굴리고, Mintlify는 "유료로 관리해줄 테니 디자인 걱정하지 마라"라며 SaaS 회사들의 문서를 사로잡았고, Astro가 Starlight라는 문서 테마를 내놓으며 새 강자로 떠올랐다. Nextra는 Next.js로 문서를 짓고 싶은 사람의 선택, VitePress는 Vue 진영의 답이다.

그리고 죽거나 죽어가는 진영도 있다. **Gatsby** — 한때 React 진영의 SSG였지만 Netlify에 인수된 뒤 사실상 유지보수 모드로 들어갔다. 새로 시작하는 프로젝트가 Gatsby를 고르는 일은 2026년 거의 없다. **Jekyll** — Ruby의 원조 SSG, GitHub Pages의 기본값. 여전히 굴러가지만 모멘텀은 완전히 잃었다. **Hexo** — 노드 진영의 옛 강자, 한국·중국에서 일부 잔존. **Zola** — Rust로 만든 빠른 SSG, 모멘텀은 있지만 생태계가 얇다.

이 글은 11개 SSG를 같은 축으로 정면 비교한다. 비교 후 네 가지 시나리오 — **회사 블로그**, **개인 블로그/포트폴리오**, **OSS 라이브러리 문서**, **SaaS API 문서** — 에서 어떤 도구를 골라야 하는지 따져본다. 그 다음은 2026년 SSG의 새 변수 — AI 검색·번역·자동 콘텐츠 — 가 도구 선택을 어떻게 바꾸는지 본다.

> 같은 카테고리의 도구라도 **콘텐츠 모델**과 **운영 모델**이 다르면 결과가 완전히 다르다. 1년 운영한 뒤 도구를 바꾸는 비용은 처음 도입 비용의 10배가 든다.

가격·기능 수치는 빠르게 바뀐다. 이 글의 모든 숫자는 **2026년 5월 기준**이며, 구조적 차이에 집중한다. 6개월 뒤 숫자가 바뀌어도 의사결정 프레임은 유효해야 한다.

1장 · 비교 축 — 무엇을 보고 골라야 하는가

11개 도구를 9개 축으로 분해한다. 축 자체가 의사결정 프레임이다.

**축 1 · 카테고리 적합성**

도구가 콘텐츠 사이트에 강한가, 문서 사이트에 강한가, 둘 다인가. Hugo·Eleventy는 콘텐츠 강자, MkDocs·Docusaurus·Mintlify는 문서 강자, Astro는 둘 다, Next.js 자체는 풀스택. 카테고리를 무시하면 6개월 뒤 후회한다.

**축 2 · 빌드 속도**

페이지 수가 늘었을 때의 빌드 시간 곡선. Hugo는 압도적으로 빠르다(Go 컴파일 + 동시 처리), Zola가 그다음(Rust), 그 외 자바스크립트 진영은 모두 비슷한 구간에서 경쟁한다. 페이지 천 개를 넘어가면 차이가 크게 벌어진다.

**축 3 · 콘텐츠 모델**

마크다운만 받는가, MDX(JSX in Markdown)를 받는가, AsciiDoc·reStructuredText도 받는가. 자유 폼 콘텐츠를 다룰 때 결정적이다. MDX는 React 컴포넌트를 본문에 박을 수 있어 인터랙티브 위젯을 넣기 쉽다. 단점은 콘텐츠가 코드에 결합되어 마이그레이션이 어렵다.

**축 4 · 테마·디자인 자유도**

완전 자유 폼인가, 기본 테마가 있고 커스터마이즈만 가능한가. MkDocs Material, Mintlify, Starlight는 디자인이 거의 정해져 있다. Hugo·Eleventy·Astro는 백지에서 시작한다. 디자인 자유도와 시작 속도는 트레이드오프다.

**축 5 · 검색**

내장 검색이 있는가, 외부 통합인가, AI 검색이 있는가. MkDocs Material은 lunr.js 기반 클라이언트 검색을 내장. Docusaurus는 Algolia DocSearch를 추천. Mintlify는 AI 검색을 기본 제공. Inkeep/Kapa.ai 같은 AI 검색 SaaS와의 통합도 점점 표준이 되고 있다.

**축 6 · 다국어(i18n)**

다국어 라우팅·번역 워크플로 지원. Docusaurus, Astro, Hugo는 1급 지원. Eleventy는 플러그인. MkDocs는 i18n 플러그인 필요. Jekyll은 어렵다. 다국어가 필요하면 후보가 절반으로 줄어든다.

**축 7 · 배포·호스팅 모델**

어디에 호스팅할 수 있는가. 정적 빌드를 뱉어내는 도구는 모두 GitHub Pages, Cloudflare Pages, Vercel, Netlify에 배포 가능. Mintlify는 자체 호스팅(SaaS) 모델이라 선택권이 없다. 자가 호스팅 vs SaaS는 비용·통제·속도의 트레이드오프.

**축 8 · 가격 / 비용**

오픈소스인가, 일부 유료인가, 완전 SaaS인가. Mintlify는 유료(`Starter` 무료, `Pro` 월 150달러, `Growth` 월 550달러 수준, 2026년 기준 변동 가능). MkDocs Material은 OSS이지만 `Insiders` 후원 티어가 있다. 나머지는 대체로 OSS + 자기 호스팅 비용.

**축 9 · AI 통합 / 미래 적합성**

LLM 친화적인 콘텐츠 모델인가, AI 검색을 붙이기 쉬운가, `llms.txt` 같은 새 표준을 지원하는가. Mintlify가 가장 앞서고, Docusaurus·Starlight도 빠르게 따라가고 있다. 2026년 문서 사이트의 가장 큰 트래픽 원천 중 하나는 검색엔진이 아니라 LLM이다.

이 9개 축을 머리에 넣고, 이제 도구를 하나씩 본다. 각 장은 같은 틀로 정리한다.

2장 · Hugo — Go의 속도, 11년의 안정성

**카테고리 · 강점**

Go로 짠 SSG. 2013년 첫 릴리스, 2026년 기준 v0.140+ 시리즈. 한 단어로 요약하면 **속도**다. 1만 페이지를 1분 안에 빌드한다. JS 진영에서 도저히 따라잡지 못하는 영역이다. 게다가 외부 의존성 없는 단일 바이너리라 CI 캐싱·재현이 단순하다.

**콘텐츠 모델**

마크다운 + YAML/TOML 프런트매터. 디렉토리 기반 라우팅. `content/posts/` 하위에 마크다운을 넣으면 자동으로 사이트 트리에 들어간다. 다국어는 `content.ko/` `content.en/` 같은 별도 디렉토리 또는 파일명 접미사로 처리. Shortcode 시스템으로 본문에 위젯을 박을 수 있지만 MDX만큼 자유롭진 않다.

**테마**

공식 테마 갤러리가 풍부하다. PaperMod, Hello Friend, Stack, Doks 등이 메인. 하지만 직접 짜는 길도 단순하다 — Go 템플릿이 어색하긴 해도 한 번 익히면 일관성이 좋다.

**검색**

내장 검색 없음. Fuse.js, Lunr.js, Pagefind, Algolia 같은 외부 검색을 직접 붙인다. Pagefind가 2026년 가장 인기 있는 선택지 — 정적 인덱스를 빌드 타임에 만들어 클라이언트에서 검색.

**약점**

Go 템플릿 문법(`{{ .Title }}` 같은)이 자바스크립트 개발자에게 낯설다. JSX/MDX가 없다 — 본문에 React 컴포넌트를 박는 일은 불가능. 1만 페이지 이상으로 가면 진가가 나오지만, 100~500 페이지 사이에선 Astro 같은 도구와 체감 속도 차이가 적다.

**대표 사용처**

대규모 회사 블로그, 대규모 뉴스 사이트, 뉴스레터 아카이브. 회사 한두 곳이 Hugo로 수십만 페이지를 굴리는 사례가 흔하다. 1Password Docs, Smashing Magazine 일부 섹션, 그리고 수많은 개인 블로그가 Hugo다.

3장 · Eleventy (11ty) — 자바스크립트 진영의 미니멀리스트

**카테고리 · 강점**

2018년 등장한 자바스크립트 SSG. 2024년 3.0이 정식 릴리스되어 ESM, Edge 함수, 더 빠른 빌드를 가져왔다. 핵심 철학은 **"프레임워크 없음"** — 너의 사이트는 너의 사이트이고, 11ty는 단지 마크다운을 HTML로 변환하는 도구일 뿐이다. JAMstack 순수주의자들의 사랑.

**콘텐츠 모델**

마크다운, Liquid, Nunjucks, Handlebars, EJS, JavaScript, TypeScript, HTML — 거의 모든 템플릿 언어를 받는다. 한 사이트 안에서 페이지마다 다른 템플릿 엔진을 써도 된다. 이 자유도가 11ty의 정체성이다.

**테마**

공식 테마가 거의 없다. 시작 템플릿(starter)이 몇 개 있고, 대부분 사용자가 직접 짠다. eleventy-base-blog, eleventy-excellent 같은 시작 템플릿이 인기.

**검색**

**카테고리 · 강점**

Vercel이 만든 Next.js 기반 문서 테마. Next.js로 다른 사이트를 굴리는 회사가 문서도 같은 스택에서 굴리고 싶을 때의 선택. 2024년 v3, 2025년 v4. Server Components 위에서 도는 SSG/SSR 하이브리드.

**콘텐츠 모델**

MDX + Next.js App Router. 사이드바는 `_meta.json` 파일들로 디렉토리마다 정의. 검색은 FlexSearch 또는 Algolia.

**테마**

Docs 테마와 Blog 테마. 디자인은 평이하지만 Next.js의 모든 기능을 그대로 쓸 수 있는 게 장점.

**약점**

Next.js 의존성이 무겁다. 단순 문서를 위해 Next.js 전체 빌드 체인을 끌어들이는 게 과한 경우가 많다. 빌드 속도도 가벼운 SSG보다 느리다.

**대표 사용처**

SWR, Turborepo, 그 외 Vercel 진영 OSS. Next.js를 이미 쓰고 있는 회사의 사내 문서.

10장 · VitePress — Vue 진영의 MkDocs

**카테고리 · 강점**

Vue 코어 팀이 만든 Vite 기반 문서 SSG. **MkDocs Material을 자바스크립트 진영에 다시 만든 듯한** 도구 — 깔끔한 기본 테마, 빠른 빌드, Vue 컴포넌트를 본문에 박을 수 있는 마크다운 확장. 2024년 v1, 2025년 v2 시리즈.

**콘텐츠 모델**

마크다운 + Vue 컴포넌트(MDX는 아니지만 비슷한 기능). 사이드바는 설정 파일에서. 빌드는 Vite 위라 매우 빠르다.

**테마**

Vue 공식 문서 스타일이 디폴트. 디자인이 단단하고 일관성 있다. 커스터마이즈는 Vue 컴포넌트 오버라이드 모델.

**약점**

Vue 진영 밖에선 모멘텀이 작다. React 컴포넌트를 본문에 박을 수 없다. 다국어는 1.x 후반에 들어왔지만 Docusaurus만큼 성숙하지 않다.

**대표 사용처**

Vue.js, Vite, Pinia, Nuxt 일부, Vitest. Vue 진영 OSS의 표준. Vue를 안 쓰는 회사가 VitePress로 가는 일은 거의 없다.

11장 · Gatsby · Jekyll · Zola — 잔존 그룹

**Gatsby — 사실상 끝**

2015년 React SSG의 출발점이었다. GraphQL 데이터 레이어, 플러그인 생태계, 잘 만든 마케팅. 2020~2022년 React SSG의 표준이었다. 그러나 Next.js의 SSG/SSR 통합이 강해지고, Astro가 콘텐츠 사이트를 가져가고, Netlify가 Gatsby를 인수한 뒤 회사가 사실상 유지보수 모드로 들어가면서 2024년 이후 신규 도입이 급격히 줄었다. 기존 Gatsby 사이트는 유지하지만, 새로 Gatsby를 고르는 결정은 2026년 거의 없다.

**Jekyll — 살아는 있지만**

2008년 GitHub 공동창업자 Tom Preston-Werner가 만든 Ruby SSG. GitHub Pages의 기본 SSG로 수많은 개인 블로그·문서가 Jekyll 위에 있다. 안정적이지만 모멘텀은 완전히 잃었다. Ruby 의존이 부담스럽고, MDX/JSX/Vue가 없고, 빌드도 느린 편. 이미 굴러가는 Jekyll 사이트는 그대로 두면 되지만, 신규에 추천하는 사람은 드물다.

**Zola — Rust의 떠오르는 별**

Rust로 짠 SSG. 단일 바이너리, 매우 빠른 빌드, Tera 템플릿. Hugo와 가장 비슷한 자리에 있다. 단점은 생태계가 얇다는 것 — 테마 수, 플러그인 수, 커뮤니티 규모가 Hugo와 비교가 안 된다. 모멘텀은 있고, "Hugo가 너무 거대해서 단순한 게 좋다"는 사람들에게 인기.

**Hexo — 한·중 진영의 잔존**

노드 진영의 옛 강자. 중국·한국 일부에서 여전히 쓰이지만 전 세계적 모멘텀은 거의 없다.

12장 · 카테고리 매트릭스 — 한눈에 보기

| 도구 | 카테고리 | 언어 | 콘텐츠 모델 | 빌드 속도 | 디자인 자유도 | 검색 | i18n | 가격 |

| --- | --- | --- | --- | --- | --- | --- | --- | --- |

| Hugo | 콘텐츠 | Go | Markdown + Shortcode | 매우 빠름 | 높음 | 외부 | 1급 | OSS |

| Eleventy 3 | 콘텐츠 | JS | Markdown + 다중 템플릿 | 빠름 | 매우 높음 | 외부 | 플러그인 | OSS |

| Astro | 둘 다 | JS/TS | MDX + Astro | 빠름 | 높음 | 외부/Pagefind | 1급 | OSS |

| Docusaurus | 문서 | JS/TS | MDX | 느린 편 | 보통 | Algolia | 1급 | OSS |

| Mintlify | 문서 | (관리형) | MDX | 즉시 | 낮음(고정 테마) | AI 내장 | 지원 | 유료 SaaS |

| Starlight | 문서 | JS/TS | MDX + Astro | 빠름 | 보통 | Pagefind 내장 | 1급 | OSS |

| Nextra | 문서 | JS/TS | MDX | 보통 | 보통 | FlexSearch/Algolia | 1급 | OSS |

| VitePress | 문서 | JS/TS | Markdown + Vue | 빠름 | 보통 | 내장 | 부분 | OSS |

| Gatsby | 둘 다 | JS | MDX(별도) | 느림 | 높음 | 외부 | 1급 | OSS(사양세) |

| Jekyll | 둘 다 | Ruby | Markdown + Liquid | 느림 | 높음 | 외부 | 어려움 | OSS |

| Zola | 콘텐츠 | Rust | Markdown + Tera | 매우 빠름 | 높음 | 외부 | 1급 | OSS |

> 이 표는 큰 그림이다. 도구마다 강한 시나리오가 다르므로, 다음 장의 시나리오 매트릭스를 같이 보라.

13장 · 시나리오 매트릭스 — 어떤 도구를 골라야 하는가

네 가지 시나리오를 정의하고, 각 시나리오에 어떤 도구가 1순위·2순위인지 본다.

**시나리오 A · 개인 블로그 / 포트폴리오**

요구사항: 마크다운 작성, 빠른 빌드, GitHub Pages 또는 Cloudflare Pages에 무료 배포, RSS, 잘 짜인 SEO, 다크 모드.

- 1순위: **Astro** — 시작 템플릿이 풍부하고, 콘텐츠 컬렉션이 깔끔하고, 빌드 결과가 가볍다.

- 2순위: **Hugo** — 글이 많아지면 빌드 속도 차이가 보인다.

- 3순위: **Eleventy** — 자바스크립트 진영 미니멀리스트라면.

**시나리오 B · 회사 블로그 / 마케팅 사이트**

요구사항: 디자인 자유도, 인터랙티브 위젯, 다국어, CMS 통합(Notion/Sanity/Contentful), Vercel/Cloudflare 배포.

- 1순위: **Astro** — MDX + 다중 프레임워크 + i18n + CMS 통합 다 강함.

- 2순위: **Next.js + 콘텐츠 솔루션** — 본격 풀스택이 필요하면.

- 3순위: **Hugo** — 디자인 자유도가 높고, 다국어 지원이 검증됨.

**시나리오 C · OSS 라이브러리 문서**

요구사항: 마크다운 작성 편의, i18n, 버전 관리(v1/v2/v3 병행), 검색, OSS 친화적 라이선스, 커뮤니티 기여 쉬움.

- 파이썬 진영: **MkDocs Material** — 사실상 표준. 다른 거 안 고르면 후회 없음.

- React/JS 진영: **Docusaurus** — 메타·OSS 커뮤니티의 검증.

- 새 프로젝트: **Starlight** — 작고 빠르게 시작할 때 우월.

- Vue 진영: **VitePress** — 다른 선택지 없음.

**시나리오 D · SaaS API 문서**

요구사항: OpenAPI 자동 렌더링, API 플레이그라운드, AI 검색, 빠르고 멋있게, 디자이너 시간 절약.

- 1순위: **Mintlify** — 돈으로 시간 사는 도구. 디자인·AI 검색·OpenAPI 자동화 다 패키지.

- 2순위: **Docusaurus + redocusaurus + Algolia + Kapa.ai** — 자가 호스팅 + 통합. 비용 절감 가능하지만 손이 많이 감.

- 3순위: **Starlight + OpenAPI 플러그인** — 모멘텀 있음.

**시나리오 E · 회사 내부 위키 / 변경 로그**

- 1순위: **MkDocs Material** 또는 **Docusaurus** — 어느 쪽이든 검증됨. 팀 언어가 파이썬이면 전자, JS면 후자.

- 2순위: **Starlight** — 작은 팀이 빠르게 시작할 때.

14장 · AI 시대의 문서 — 새 변수들

2026년 문서 사이트를 만든다는 건 **사람이 읽을 페이지를 만든다**는 것 이상이다. LLM이 읽고 답한다. 그래서 새 변수가 셋 있다.

**변수 1 · `llms.txt` / `llms-full.txt`**

사이트 루트에 `llms.txt`를 두면 LLM이 사이트 구조를 빠르게 이해한다. 2025년 후반에 사실상 표준이 되었다. Mintlify는 자동 생성. Docusaurus, Starlight도 플러그인 지원. 안 두면 ChatGPT나 Perplexity가 사이트를 제대로 인덱싱하지 못한다.

**변수 2 · 사이트 내 AI 검색**

페이지 검색만으론 부족하다. 사용자가 "어떻게 X를 하나요?"라고 물으면 LLM이 문서에서 답을 합성해 줘야 한다. Mintlify는 기본 내장. 그 외는 **Kapa.ai**, **Inkeep**, **Mendable**, **Algolia AI** 같은 SaaS를 붙인다. 비용은 월 200~1,000달러 수준. 회사 문서 트래픽이 월 10만이 넘으면 도입 검토.

**변수 3 · 구조화된 콘텐츠**

LLM이 잘 인용하는 페이지는 `<title>`, `<h1>`, 코드 블록 언어, 메타 설명, OG 태그가 정확하다. SSG가 이 메타데이터를 자동 생성하는가, 작가가 일일이 적어야 하는가가 문서 사이트의 LLM 친화도를 결정한다. Mintlify·Starlight·Docusaurus가 강하다. 자가 빌드 솔루션은 종종 약하다.

> 2026년 문서 트래픽의 30~50%는 LLM이 합성한 답에서 온다. 사람이 직접 읽는 페이지뷰는 줄어들고, **LLM이 인용하는 페이지뷰**가 늘어난다. 이 변화에 대응하지 않는 문서 사이트는 6개월 뒤 묻혀버린다.

15장 · 마이그레이션 비용 — 도구를 바꾼다는 것

1년 운영한 SSG를 바꾸는 비용은 처음 도입 비용의 10배다. 그래서 처음 고르는 게 중요하다. 마이그레이션 시 드는 일을 분해해보면.

- **콘텐츠 변환** · 마크다운 사이는 비교적 쉽지만, 프런트매터 필드명·shortcode·MDX 컴포넌트가 다르면 일괄 변환 스크립트가 필요. 대규모 사이트에선 며칠.

- **URL 보존** · 옛 URL을 그대로 유지하지 않으면 SEO가 무너진다. 라우팅 규칙을 신중히 옮기고, 1년치 리다이렉트 규칙을 둔다.

- **검색 인덱스 재구축** · Algolia 인덱스나 자체 인덱스를 다시 만든다. 검색 품질이 바뀌어 사용자가 짜증낸다.

- **디자인 재현** · 100% 픽셀 일치는 어렵다. 일부 페이지에서 작은 차이가 나며, 한동안 사용자가 "옛 모습이 좋았다"고 한다.

- **빌드 파이프라인** · CI 설정, 캐싱, 배포 훅, preview 환경을 새 도구에 맞게 다시 만든다.

- **저자 워크플로 재교육** · 기존 저자들이 새 도구의 마크다운 확장·MDX 컴포넌트를 익혀야 한다. 일주일은 잡는다.

마이그레이션 안 하는 게 최선이고, 한다면 **카테고리 안에서만** 옮긴다(예: MkDocs Material → Starlight는 비교적 쉽다, MkDocs → Docusaurus는 어렵다, MkDocs → Mintlify는 자동 마이그레이션 도구가 일부 있지만 검수 필수).

16장 · 에필로그 — 의사결정 체크리스트와 안티패턴

도구를 고를 때 체크리스트

1. **사이트의 카테고리는 무엇인가** — 블로그/마케팅 사이트인가, 기술 문서인가, 둘 다인가. 답에 따라 후보가 절반으로 줄어든다.

2. **콘텐츠 모델은 무엇인가** — 마크다운만 받는가, MDX가 필요한가, 인터랙티브 위젯이 필요한가.

3. **저자는 누구인가** — 마크다운에 익숙한 엔지니어인가, 평범한 콘텐츠 작가인가, 마케터인가. 답에 따라 CMS 통합 필요 여부가 결정.

4. **언어는 몇 개인가** — 한국어 한 개면 자유롭게, 다섯 개면 i18n 1급 지원 도구만 후보.

5. **빌드 시간 / 페이지 수** — 100 페이지는 어느 도구든 빠르다. 1만 페이지는 Hugo·Zola.

6. **검색 / AI 검색이 필요한가** — 필요하다면 Mintlify·MkDocs Material·Starlight가 유리.

7. **배포·호스팅** — 자가 호스팅 OK인가, SaaS만 가능한가. Mintlify는 SaaS 전용.

8. **연 1만 달러 예산을 쓸 수 있는가** — 가능하면 Mintlify, 아니면 OSS.

9. **앞으로 5년 운영할 수 있는가** — 이미 사양세인 도구(Gatsby)는 피한다.

흔한 안티패턴

1. **"Next.js 풀스택"으로 단순 블로그를 시작한다** — 5페이지 짜리 블로그에 App Router·Server Components가 필요하지 않다. Astro나 Hugo가 더 작고 안정적.

2. **AI 진영의 새 도구만 좇는다** — Mintlify가 좋아 보여도 연 1만 달러를 쓸 준비가 안 됐다면, MkDocs Material·Starlight로 시작해 점차 AI 검색을 붙이는 게 합리적.

3. **카테고리를 무시한다** — 블로그용 SSG(Hugo)로 거대한 문서 사이트를 짓거나, 문서용 SSG(MkDocs)로 인터랙티브 마케팅 사이트를 짓는 일.

4. **다국어를 마지막에 생각한다** — 한국어 콘텐츠를 만든 뒤 영어·일본어를 붙이려고 보면, 도구가 i18n을 1급으로 지원하지 않아 전부 재작업. 처음부터 i18n을 결정 인자로 넣어라.

5. **검색을 마지막에 생각한다** — Algolia DocSearch 신청을 안 하고 자체 검색을 짜다 6개월이 간다. 초기에 결정해 통합해두라.

6. **사양세 도구로 신규 시작한다** — 2026년에 Gatsby·Hexo·Jekyll로 신규를 시작하는 건 5년 뒤를 생각하면 위험. 이미 굴러가는 사이트는 그대로 두되, 신규는 모멘텀 있는 도구로.

7. **마이그레이션을 가볍게 본다** — "그냥 다른 SSG로 옮기면 되지"가 1주일 작업이라고 생각하지만 실제론 1~3개월.

8. **빌드 속도를 무시한다** — 100 페이지로 시작했다가 1년 뒤 3,000 페이지가 되면 CI 빌드가 30분이 걸려 모든 PR이 느려진다. 페이지 증가 곡선을 예측하라.

다음 글 예고

다음 글에서는 **MkDocs Material로 회사 내부 문서 사이트를 0에서 운영까지** — 디렉토리 구조, 다국어, 검색, 권한, CI 빌드, 그리고 AI 검색을 붙이는 실제 단계까지 본다.

그리고 그 다음은 **Astro Starlight vs Docusaurus 정면 마이그레이션** — 같은 OSS 문서를 두 도구로 다 빌드해보고 무엇이 다른지의 정량 기록.

참고 / References

- [Hugo — official site](https://gohugo.io/)

- [Hugo Releases — GitHub](https://github.com/gohugoio/hugo/releases)

- [Eleventy 3.0 release notes](https://www.11ty.dev/blog/three/)

- [Eleventy — official docs](https://www.11ty.dev/docs/)

- [Astro — official site](https://astro.build/)

- [Astro Content Collections docs](https://docs.astro.build/en/guides/content-collections/)

- [MkDocs Material — official docs](https://squidfunk.github.io/mkdocs-material/)

- [MkDocs Material Insiders](https://squidfunk.github.io/mkdocs-material/insiders/)

- [Docusaurus — official site](https://docusaurus.io/)

- [Docusaurus 3 release notes](https://docusaurus.io/blog/releases/3.0)

- [Mintlify — docs platform](https://mintlify.com/)

- [Mintlify Pricing](https://mintlify.com/pricing)

- [Starlight by Astro — docs](https://starlight.astro.build/)

- [Nextra — Next.js docs theme](https://nextra.site/)

- [VitePress — Vue docs SSG](https://vitepress.dev/)

- [Pagefind — static search](https://pagefind.app/)

- [Algolia DocSearch](https://docsearch.algolia.com/)

- [Inkeep — AI search for docs](https://inkeep.com/)

- [Kapa.ai — AI for technical docs](https://www.kapa.ai/)

- [llms.txt — proposed standard](https://llmstxt.org/)

- [Jekyll — official site](https://jekyllrb.com/)

- [Zola — Rust SSG](https://www.getzola.org/)

- [Gatsby — Netlify acquired (2023)](https://www.netlify.com/press/netlify-acquires-gatsby/)