문서 사이트를 만들 때 병목은 대개 글쓰기 전에 온다. 프레임워크를 고르고, 템플릿을 붙이고, 검색·SEO·배포 구조를 챙기다 보면 정작 중요한 문서 작성은 뒤로 밀린다.
Blume은 이 출발점을 바꾸려는 오픈소스 문서화 프레임워크다. 개발자 Hayden Bleasel이 공개했으며, MIT 라이선스로 배포된다. Blume v1.0.0은 2026년 7월 13일 공개됐고, 기사 작성 시점의 최신 버전은 v1.0.3이다.1
핵심은 단순하다. Blume은 Markdown 또는 MDX 파일이 들어 있는 폴더를 읽어, 내부적으로 Astro 기반 문서 사이트를 생성한다.1 사용자는 처음부터 문서 사이트 프로젝트를 설계하기보다, 이미 갖고 있는 문서 폴더를 사이트로 바꾸는 방식에 가깝게 접근할 수 있다.
Blume의 핵심: 폴더에서 문서 사이트로
Blume이 말하는 “제로 설정”은 설정이 아예 없다는 뜻이 아니다. 기본값으로 바로 시작하고, 필요할 때만 blume.config.ts로 조정하는 방식이다.
CLI는 콘텐츠와 설정 파일을 읽어 .blume/ 아래에 숨겨진 Astro 프로젝트를 만들고, 개발 서버와 빌드를 실행한다.1 따라서 사용자는 Astro나 Tailwind를 직접 구성하지 않아도 된다.2 문서 작성자는 라우팅, 테마, 빌드 파이프라인보다 문서의 구조와 내용에 집중할 수 있다.
이 접근은 특히 문서화가 개발 흐름의 일부가 되어야 하는 팀에 유용하다. 별도 웹 프로젝트를 관리하는 부담을 줄이고, Markdown/MDX 파일을 중심으로 문서를 계속 갱신할 수 있기 때문이다.
기본 문서 경험을 처음부터 갖춘다
문서 사이트는 단순히 페이지를 나열하는 것만으로는 부족하다. 사용자는 검색할 수 있어야 하고, 구조를 빠르게 파악할 수 있어야 하며, 필요한 예제와 안내를 자연스럽게 따라갈 수 있어야 한다.
Blume은 이런 기본값을 미리 포함한다. 로컬 검색, 테마, 내비게이션, OGP 이미지, SEO 요소를 제공하고,2 MDX에서는 콜아웃, 탭, 단계, 파일 트리 같은 30개 이상 컴포넌트를 별도 import 없이 사용할 수 있다.3
중요한 점은 이 기능들이 “나중에 붙일 부가 기능”이 아니라는 것이다. 작은 오픈소스 프로젝트나 초기 제품 문서라도 검색이 없고, 안내 흐름이 끊기고, 예제가 흩어져 있으면 사용자는 금방 이탈한다. Blume은 문서 사이트의 기본 기대치를 처음부터 충족하도록 설계된 도구에 가깝다.
사람뿐 아니라 AI가 읽는 문서
Blume에서 눈에 띄는 또 다른 방향은 AI 대응이다. Blume은 llms.txt, llms-full.txt, 각 페이지의 Markdown 버전, Ask AI, 내장 MCP 서버를 제공한다.1
이는 문서를 사람에게 보여주는 웹페이지로만 보지 않는다는 뜻이다. 코딩 에이전트나 AI 도구가 문서를 검색하고, 원문 Markdown을 가져오고, 문맥 자료로 활용할 수 있게 만드는 구조다. MCP는 AI 에이전트가 외부 도구나 데이터에 접근하도록 연결하는 프로토콜이다.
앞으로 개발 문서는 “보기 좋은 사이트”를 넘어 “기계가 읽고 활용하기 쉬운 지식 베이스”가 되어야 한다. Blume은 이 변화를 문서 프레임워크의 기본 기능 안으로 끌어들인다.
도입 전에 확인할 것
Blume은 제품 문서, API 문서, 오픈소스 프로젝트 문서처럼 Markdown/MDX 기반으로 지속 관리되는 문서에 잘 맞는다. 정적 HTML로 빌드해 Vercel, Netlify, Cloudflare Pages, GitHub Pages, S3 등에 배포할 수 있다.1
다만 모든 기능이 같은 운영 모델을 요구하는 것은 아니다. 일반 문서 사이트처럼 정적 빌드만으로 충분한 경우가 있는 반면, Ask AI나 MCP 서버처럼 요청 시 처리가 필요한 기능을 쓰려면 서버 출력과 어댑터 선택이 필요하다.2
따라서 도입 판단은 간단한 질문에서 시작하면 된다.
Markdown/MDX 문서 폴더를 중심으로 사이트를 만들고 싶은가?
검색, 내비게이션, SEO, MDX 컴포넌트를 직접 붙이는 시간을 줄이고 싶은가?
AI 도구가 읽고 활용할 수 있는 문서 구조까지 고려해야 하는가?
정적 문서로 충분한가, 아니면 Ask AI·MCP 같은 서버 기능도 운영할 것인가?
Blume의 메시지는 분명하다. 문서화의 출발점은 프레임워크 설정이 아니라 Markdown 폴더가 될 수 있다. 팀이 문서 사이트 관리보다 문서 자체에 더 많은 시간을 쓰고 싶다면, Blume은 충분히 검토할 만한 선택지다.
1Markdownからドキュメントサイトを構築、Astro/ViteベースのOSS「Blume」v1が公開 | gihyo.jp
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.