haydenbleasel/blume 딥다이브
— 클론할 스타터가 없는 마크다운-우선 문서 프레임워크

1프로젝트 한 줄 요약

가장 작은 시작 예시가 이 도구의 성격을 압축한다. 클론할 저장소도, 배울 폴더 구조도, 설정 보일러플레이트도 없다:

# 1) 스캐폴드 — docs/index.mdx + blume.config.ts 하나
npx blume init

# 2) 핫 리로드 개발 서버 (Astro는 뒤에서 자동 생성)
blume dev

# 3) 정적 HTML + 로컬 검색 인덱스 빌드 → dist/
blume build

설정 파일조차 거의 비어 있어도 완전히 동작한다. 아래가 blume 설정의 전부일 수 있다 — 나머지는 전부 합리적 기본값이다:

// blume.config.ts — defineConfig는 타입 추론용 순수 헬퍼
import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  theme: { accent: "teal" },
});
// defineConfig({}) 처럼 완전히 비워도 사이트가 뜬다 (제로 설정)

정리하면 blume의 정체는 "라이브러리"가 아니라 "코드 생성 CLI + Astro 런타임"의 하이브리드다. ① CLI(blume)가 설정과 콘텐츠를 읽어 페이지 그래프를 만들고, ② 그걸로 .blume/에 진짜 Astro 프로젝트를 생성해 astro dev/astro build를 구동하며, ③ 내가 만든 마크다운·오버라이드·테마를 그 안으로 주입한다. 문서의 "예쁨·빠름"은 Astro·Tailwind에서 오고, 이 레포의 진짜 가치는 그 모든 걸 감춰 "콘텐츠만 만지게" 만든 오케스트레이션 엔지니어링에 있다.

저자는 Hayden Bleasel(Kibo UI·Ultracite 등으로 알려진 OSS 저자)이며 MIT로 공개했다. "Free and open source, forever"를 내걸었고, 문서 사이트(useblume.dev)는 blume으로 만든 blume 문서 — 즉 스스로를 도그푸딩하는 구조다.

2왜 주목받는가 — "제로 설정 + AI-네이티브"의 무게

문서 사이트를 세우려는 개발자에게 지금까지 선택지는 저마다 어딘가 무거웠다. 스타터를 클론해 앱을 떠안거나(Docusaurus·Nextra), 호스팅에 묶이거나(Mintlify), 특정 프레임워크에 종속됐다(Fumadocs=Next.js). blume은 그 무게들을 정확히 겨냥한다.

차별점 ① — 클론할 스타터가 없다: "프레임워크가 곧 템플릿"

다른 도구는 git clone starter로 시작해 그 앱을 영원히 소유한다 — 의존성 업그레이드도, 빌드 설정도 내 책임이다. blume은 정반대다. 내 폴더엔 마크다운과 (선택) blume.config.ts만 있고, Astro 프로젝트는 blume이 매 실행마다 .blume/에 새로 만든다. 프레임워크가 곧 스타터라, "업데이트=blume 버전만 올리기"가 된다.

차별점 ② — AI-네이티브를 1급 기능으로 내장

blume은 "AI-ready"를 표방하는데, 이는 마케팅 문구가 아니라 코드로 들어 있다. 빌드 시 llms.txt·llms-full.txt를 생성하고, 모든 페이지에 원본 마크다운을 .md URL로 제공하며, "Copy as Markdown"·"Open in chat" 액션을 붙인다. 나아가 호스팅 MCP 서버까지 내장해, 코딩 에이전트가 문서를 직접 검색·조회하게 만든다.

차별점 ③ — 정적 우선(빠름), 서버 기능은 opt-in

기본 테마는 클라이언트 프레임워크 JS를 배포하지 않는다 — Astro의 "제로 JS 기본"을 따라 Core Web Vitals가 좋다. Ask AI·MCP 같은 요청 시간 기능이 필요할 때만 서버 출력으로 전환한다. 심지어 prepare.ts에 하드 게이트가 있어, 서버 전용 기능을 정적 빌드에 넣으면 BLUME_SERVER_FEATURE_REQUIRED 에러로 멈춰 "느려지는 실수"를 코드로 막는다.

3기술 스택 전체 지도 — Astro 7·Bun 모노레포·최신 툴체인

blume은 "프론트/백엔드"로 나뉘는 웹 앱이 아니라, 배포되는 npm 패키지 하나(blume)가 사용자 기기에서 Astro 프로젝트를 생성·구동하는 도구다. 스택을 이해하려면 세 묶음으로 보면 빠르다: 렌더링을 담당하는 Astro 코어, 콘텐츠·검색·AI를 처리하는 기능 엔진, 그리고 이 패키지를 개발·빌드하는 툴체인.

① 렌더링 코어 — Astro 7 + React 19 + Tailwind v4

blume이 생성하는 숨은 프로젝트의 심장은 Astro다. 정적·서버 렌더링을 모두 지원하고, 인터랙티브 조각만 골라 하이드레이션하는 "아일랜드" 모델을 쓴다.

② 기능 엔진 — 콘텐츠·검색·AI·구문 하이라이팅

여기가 blume의 "부가가치"가 몰린 층이다. 마크다운을 읽고, 검색 인덱스를 만들고, AI가 읽을 형태로 변환하고, 코드를 예쁘게 칠한다.

③ 툴체인 — TS 6(tsgo)·Oxlint/Oxfmt·Bun test·Changesets

blume 저장소 자체를 개발하는 도구들인데, "2026년 최신 프론트엔드 툴체인의 축소판"이라 그 자체로 볼거리다.

4아키텍처 심화 — 숨은 Astro 프로젝트를 생성해 구동한다

이 레포에서 가장 배울 게 많은 부분이다. "문서 도구를 어떻게 만드느냐"에는 흔히 두 길이 있다 — 라이브러리로 컴포넌트를 export하거나(Fumadocs), 스타터 앱을 배포하거나(Docusaurus). blume은 제3의 길을 간다: 코드를 생성하는 CLI가 되어, 실행 때마다 완전한 Astro 앱을 만들어 돌린다.

전체 데이터 흐름

CLI 진입점 — citty 서브커맨드

CLI는 UnJS의 citty로 짜였다. 11개 서브커맨드가 한 곳에 등록되고, 원격 소스용 토큰(예: GITHUB_TOKEN)을 .env에서 로드한다.

// src/cli/index.ts — 모든 서브커맨드의 등록소
const main = defineCommand({
  meta: { name: "blume", version: getBlumeVersion(),
          description: "Markdown-first documentation powered by Astro and Vite." },
  subCommands: { add, audit, build, check, dev, doctor,
                 eject, init, preview, sync, validate },
});
loadEnvFiles(process.cwd());   // 원격 소스 토큰 로드
runMain(main);

핵심 설계 패턴 4가지

패턴 ① — 숨은 런타임 생성(generated runtime)을 캐시처럼 취급

.blume/는 사용자가 소유하는 코드가 아니라 매 실행마다 재생성되는 산출물이다. 그래서 dev 커맨드가 흥미롭다 — 파일을 watch하다가, "페이지가 추가/삭제/리네임된 구조적 변경"과 "본문만 고친 편집"을 구분한다. 전자는 서버를 재시작하고, 후자는 Vite HMR 핫패스로 넘긴다. 구분의 열쇠가 route signature(정렬된 경로+엔트리ID 문자열)다.

// src/cli/commands/dev.ts — 구조 변경 감지용 서명
const routeSignature = (routes) =>
  routes.map((route) => `${route.path} ${route.entryId}`)
        .toSorted().join("\n");

// 서명이 바뀌면(=구조 변경) server.stop() → generateRuntime() → 새 서버,
// 아니면 그냥 재생성만 하고 Vite HMR에 맡김.

여기에 .blume/dev.lock 원자적 잠금(dev-lock.ts)을 두어 두 개의 dev 서버가 같은 디렉토리를 동시에 훼손하는 사고를 막는다. watch 이벤트가 폭주해도 single-flight로 재생성을 합쳐(coalesce) 처리한다.

패턴 ② — 소스 추상화(ContentSource 계약)

모든 콘텐츠 오리진이 같은 인터페이스(load()/validate()/watch())를 구현한다. 그래서 로컬 파일 + 원격 MDX + GitHub Releases + Notion + Sanity를 한 사이트에 섞어 쓸 수 있다. 레퍼런스 구현이 파일시스템 소스다.

// src/core/sources/filesystem.ts — 콘텐츠 소스 레퍼런스
const files = await glob(options.include, {        // tinyglobby
  absolute: true, cwd: contentRoot, onlyFiles: true,
  ignore: [...options.exclude, ...baselineScanIgnore()], // node_modules/.blume 제외
});
// 각 파일: gray-matter로 프론트매터/본문 분리
const parsed = matter(source);
return { body: { format, text: parsed.content },
         data: parsed.data, raw: source, ref, sourcePath };

패턴 ③ — 설정은 없어도 동작(제로 설정), 검증은 Zod로

jiti로 .ts 설정을 런타임 import하고 blumeConfigSchema.safeParse()로 검증한다. 설정 파일이 없어도 스키마 기본값으로 완전 동작한다. Zod 에러는 한 번에 전부 보여 줘 "고치고-재실행-또 실패" 루프를 막는다.

// src/core/config.ts — 없으면 빈 객체로도 파싱 성공
const parsed = blumeConfigSchema.safeParse(raw ?? {});
// OG 이미지는 절대 URL이 필요 → site URL을 알면 자동 on, 모르면 off
const ogEnabled = config.seo.og.enabled ?? Boolean(site);

패턴 ④ — eject: 일방향 승격

blume eject는 .blume/ 생성물을 사용자 소유의 독립 Astro 앱으로 변환한다(astro.config.mjs·src/·package.json 스크립트 재작성). 그 뒤로도 blume 패키지는 계속 import할 수 있다. "제로 설정으로 시작하되, 천장에 부딪히면 완전한 제어로 탈출"하는 비상구를 설계에 내장한 것이다.

5디렉토리 구조 해부

모노레포 최상위

핵심 패키지 packages/blume/

구조가 말하는 핵심 세 가지. 첫째, 사용자가 만지는 건 저장소 밖의 docs/·blume.config.ts뿐이고, 이 방대한 src/는 전부 감춰진 엔진이다. 둘째, core/(스캔·그래프)와 astro/(코드 생성)가 명확히 갈려 있어, "무엇을 렌더할지 정하는 층"과 "실제 Astro 코드를 찍어내는 층"이 분리된다. 셋째, ai/·audit/·openapi/가 독립 모듈로 존재한다는 건 AI·품질·API 문서를 곁다리가 아닌 1급 기능으로 본다는 신호다.

6학습 포인트 — 여기서 훔쳐올 설계

배울 것 ① — "코드 생성형 프레임워크" 패턴

이 레포 최고의 학습 자산. 라이브러리로 API를 노출하는 대신 완전한 프로젝트를 생성해 구동하고, 원하면 eject로 넘겨주는 하이브리드 설계는, "추상화의 편함"과 "탈출의 자유"를 동시에 주는 드문 예다. create-next-app(1회 생성 후 방치)과 라이브러리(계속 감춤)의 중간 지점을, 매 실행 재생성 + 일방향 eject로 절묘하게 잡았다.

배울 것 ② — 인터페이스로 데이터 소스를 갈아 끼우기

ContentSource라는 하나의 계약(load/validate/watch) 아래 filesystem·remote·github-releases·notion·sanity가 갈려 있다. 상위 스캐너는 소스가 로컬인지 CMS인지 전혀 모른다. "다양한 백엔드를 상위 코드 모르게 통일"하는 이 플러그형 구조는, 검색 provider(orama·algolia·typesense…)에도 똑같이 적용돼 있다 — 확장 가능한 아키텍처의 교과서다.

// src/search/providers.ts — provider를 kind로 분류해 통합 방식 결정
export const SEARCH_PROVIDERS = {
  orama:       { kind: "static", requiresServer: false, syncs: false }, // 기본값
  pagefind:    { kind: "pagefind", ... },   // 빌드 후 HTML에서 인덱스
  algolia:     { kind: "hosted", syncs: true },  // 빌드타임 업로드
  typesense:   { kind: "hosted", syncs: true },
  mixedbread:  { kind: "server", requiresServer: true }, // /api/search 프록시
  none:        { kind: "none" },
};

배울 것 ③ — dev 서버의 "정합성 엔지니어링"

route signature diff(구조 변경 vs 본문 편집 구분), 원자적 파일 락(중복 서버 방지), coalesced runner(watch 폭주를 single-flight로 합침) — 이 셋은 "파일을 watch해 재생성"하는 모든 도구가 부딪히는 실전 문제의 모범 해법이다. 빌드 도구·코드 생성기·핫 리로드를 만들 사람에게 그대로 참고서가 된다.

배울 것 ④ — AI-네이티브 문서화의 구체적 구현

"AI-ready"를 코드로 어떻게 만드는지 볼 수 있다: llms.txt 생성, 페이지별 .md 원본 노출, MCP 서버로 에이전트가 문서를 도구로 조회. MCP 도구는 4개뿐이지만 설계가 깔끔하다 — 전부 읽기 전용이라 안전하고, 검색·단일 페이지·목록·내비를 덮는다.

// src/ai/mcp/tools.ts — 코딩 에이전트에 노출하는 읽기 전용 도구 4종
export const MCP_TOOLS = [
  { name: "search_docs",    title: "Search documentation" }, // 전문 검색
  { name: "get_page",       title: "Get page Markdown" },   // 에이전트 최적 MD
  { name: "list_pages",     title: "List pages" },         // 전체 열거
  { name: "get_navigation", title: "Get navigation" },     // 내비 트리
];

배울 것 ⑤ — 2026년 프론트엔드 툴체인의 집약체

Astro 7 + React 19(+Compiler) + Tailwind v4 + TypeScript 6(tsgo) + Oxlint/Oxfmt(Rust) + Bun test + Zod 스키마 + Changesets 릴리스. 이 하나의 저장소를 읽는 것만으로 현대 스택의 조립법을 통째로 훑을 수 있다. 특히 "런타임 TS 설정 로드(jiti) + Zod 검증"은 설정 주도 도구를 만들 때 바로 쓰는 패턴이다.

7시스템 / 실행 요구사항

설정 옵션이 이 도구의 "손잡이"를 보여 준다. defineConfig({...}) 안에서 content.sources로 여러 콘텐츠 소스를 혼합하고, navigation.tabs로 상단 탭을, theme.accent로 색을, deployment.adapter로 배포 타깃을, search.provider로 검색 백엔드를, export: true로 PDF/EPUB 내보내기를 켠다. 폴더별 meta.ts(defineMeta)로 사이드바 그룹을, theme.css로 Tailwind v4 토큰을 세밀 제어한다.

// apps/docs/blume.config.ts — blume이 자신을 설정하는 실제 예시(축약)
export default defineConfig({
  title: "Blume",
  theme: { accent: "teal" },
  content: { root: "content", sources: [
    { type: "filesystem", root: "content" },
    { type: "github-releases", owner: "haydenbleasel", repo: "blume", prefix: "changelog" },
  ] },
  navigation: { tabs: [ { label: "Docs", path: "/docs" },
                        { label: "Changelog", path: "/changelog" } ] },
  deployment: { adapter: "vercel" },
  export: true, lastModified: true,
});

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 · 문서

• github.com/haydenbleasel/blume — 원본 저장소(MIT)
• useblume.dev — 공식 문서(blume으로 만든 blume 문서, 도그푸딩)
• npm — blume — 배포 패키지(v1.1.3)

핵심 배경 기술

• Astro — blume이 숨겨서 쓰는 렌더링 엔진(아일랜드 아키텍처)
• MDX · Tailwind CSS v4 — 콘텐츠 포맷 · 스타일링
• Orama — 기본 로컬 검색 엔진 · Model Context Protocol — AI 연동

도구 · 생태계

• citty — CLI 프레임워크 · Zod — 설정 스키마 검증
• Oxc(Oxlint/Oxfmt) · Turborepo · Bun — Rust 툴체인 · 모노레포 러너 · 런타임
• llms.txt 표준 — AI가 읽는 문서 색인