얼마 전, Material for MkDocs 팀이 만드는 새로운 정적 사이트 생성기(Static Site Generator)인 「Zensical」를 사용해 본 기사를 작성했습니다.

그 후로도 문서 도구를 계속 추적하던 중, 이번에는 AI 에이전트 연동을 전면에 내세운 문서 생성기(Document Generator)인 「Blume」를 발견했습니다.

공식 사이트: https://useblume.dev/

Zensical가 「Material for MkDocs의 자산을 계승하면서 고속화한다」는 방향성이었다면, Blume는 Astro / Vite 기반으로 처음부터 만들어졌으며 컨셉도 결이 다릅니다. 실제로 셋업하여 빌드까지 시도해 보았으므로, 그 내용을 정리합니다.

Blume는 "fast, AI-ready, markdown-first docs"를 표방하는 문서 사이트 생성기입니다. 폴더에 Markdown을 두는 것만으로 프로덕션 품질의 문서 사이트를 구축할 수 있습니다.

• 완전 무료·오픈 소스 (MIT 라이선스)
• 제로 컨피그(Zero Config)로 시작 가능 (내비게이션은 자동 추론)
• Astro / Vite 기반으로 고속 동작
• Node / Bun / Deno 대응

개인 프로젝트의 작은 README 사이트부터 수천 페이지 규모의 API 문서까지 확장 가능한 설계라고 합니다.

Blume를 사용하면서 가장 인상적이었던 점은, 생성된 사이트가 처음부터 AI 에이전트나 LLM이 읽는 것을 전제로 만들어져 있다는 점입니다.

• 각 페이지의 Markdown 소스를 그대로 /{route}.md로 배포 (콘텐츠 네고시에이션 (Content Negotiation))
• llms.txt / llms-full.txt를 자동 생성 (사이트 전체의 기계 가독성 인덱스)
• agent-readability.json을 통해 AI 크롤러에게 「이 사이트를 어떻게 읽어야 하는지」를 명시
• Vercel AI Gateway나 OpenRouter을 경유하여 페이지 내 AI 어시스턴트를 통합 가능
• Model Context Protocol (MCP) 서버를 표준 탑재

즉 「인간이 읽는 사이트」와 「AI 에이전트가 읽어들이는 지식원」을 동일한 Markdown 소스로부터 동시에 만든다는 설계 사상을 가지고 있습니다.

• Mermaid 다이어그램, KaTeX 수식 등의 Markdown 확장
• 다크 모드, 전체 텍스트 검색, OGP 이미지, SEO, 36개 언어 로컬라이제이션, RTL 언어 대응
• 사이트맵 · RSS · JSON-LD 자동 생성
• 30종 이상의 접근 가능한 MDX 컴포넌트 (Card, Steps, Tabs, CodeGroup, Diff 등)를 임포트 없이 이용 가능
• OpenAPI / AsyncAPI 사양을 Scalar로 통합한 API 레퍼런스 생성
• 파일 시스템뿐만 아니라 GitHub, Sanity, Notion 등을 콘텐츠 소스로 연결 가능 (커스텀 백엔드 어댑터도 대응)

npx blume init으로 프로젝트를 초기화할 수 있습니다.

npx blume init . --yes

출력 결과는 다음과 같았습니다.

[blume] ✔ Created docs/index.mdx
[blume] ✔ Created package.json
[blume] ✔ Created blume.config.ts
...

생성된 파일은 심플하며, 다음 3개뿐입니다.

docs/index.mdx
package.json
blume.config.ts

blume.config.ts는 TypeScript로 작성되어 있으며, defineConfig에 타입 보완(Type Completion)이 적용됩니다.

import { defineConfig } from "blume";
export default defineConfig({
  title: "My Docs",
  ...
});

콘텐츠 소스의 전환이나 AI 어시스턴트용 모델 설정 등도 이 파일에 추가해 나가는 형태인 것 같습니다.

docs/index.mdx에는 처음부터 프런트매터(Frontmatter)가 들어 있습니다.

---
title: Introduction
description: Welcome to your new Blume docs.
...
---

npm install

npm install을 실행한 후, npm run build (내부적으로는 blume build 실행)를 수행합니다.

npm install
npm run build

빌드 로그의 일부입니다.

[blume] ◐ Building 1 page(s) (static output)
09:28:09 [content] Synced content
09:28:09 [build] output: "static"
...

단 한 페이지뿐인 프로젝트라도 index.html뿐만 아니라 index.md (Raw Markdown), llms.txt, agent-readability.json까지 한꺼번에 출력된다는 점이 Zensical 등 다른 SSG (Static Site Generator)와의 명확한 차이점이라고 느꼈습니다.

dist/llms.txt는 사이트 전체를 요약한 인덱스 역할을 하고 있었습니다.

# My Docs
> Documentation powered by Blume.
## Docs
...

dist/index.md에는 페이지의 Raw Markdown 소스가 그대로 출력되어 있습니다 (HTML 페이지와 동일한 내용을 .md로서 별도로 배포하는 형태).

---
title: Introduction
description: Welcome to your new Blume docs.
...

dist/agent-readability.json은 AI 크롤러를 위해 사이트 구조를 선언하는 JSON 파일이었습니다.

{
"artifacts": {
"markdown": {
...

contentUsage를 통해 ai-input이나 ai-train 가능 여부를 사이트 측에서 명시할 수 있도록 되어 있는 점도, AI 크롤링을 전제로 한 도구다운 설계라고 생각했습니다.

Blume에서 개인적으로 가장 주목한 점은 문서 사이트 자체가 MCP (Model Context Protocol) 서버를 가질 수 있다는 점입니다. Claude Code와 같은 코딩 에이전트가 문서를 검색하고 가져오기 위한 도구를 직접 호출할 수 있게 됩니다.

공식 문서: https://useblume.dev/docs/configuration/ai

blume.config.ts에 다음과 같이 작성하는 것만으로 활성화할 수 있습니다.

import { defineConfig } from "blume";
export default defineConfig({
title: "My Docs",
...

설정 항목은 다음과 같습니다.

활성화하면 search_docs / get_page / list_pages / get_navigation과 같은 도구들을 MCP 클라이언트 측에서 호출할 수 있게 된다고 합니다. 단, MCP 서버는 서버 사이드 기능이므로 정적 출력이 아닌 deployment.output: "server" 설정과 어댑터 지정이 필요합니다.

export default defineConfig({
deployment: {
output: "server",
...

유사한 메커니즘으로, 페이지 내 채팅을 통해 독자의 질문에 답하는 「Ask AI」 어시스턴트도 준비되어 있습니다. 이 기능은 Vercel AI Gateway (기본값), OpenRouter, Inkeep, 또는 OpenAI 호환 엔드포인트를 백엔드로 선택할 수 있습니다.

ai: {
ask: {
enabled: true,
...

「AI에게 사이트를 검색하게 하는 경로 (MCP)」와 「사이트 상에서 AI에게 질문할 수 있는 경로 (Ask AI)」 모두를 동일한 ai 설정 블록에서 처리할 수 있다는 점이 Blume다운 특징이라고 느꼈습니다.

사이트의 건전성을 체크하는 doctor

커맨드(Command)도 준비되어 있습니다.

$ npm run doctor
[blume] ℹ Pages: 1
[blume] ℹ Output: static
...

같은 「Markdown으로부터 문서 사이트를 만드는」 도구라도, Zensical과 Blume는 목표로 하는 방향성이 상당히 다르다고 느꼈습니다.

기존의 MkDocs 자산을 활용하고 싶다면 Zensical, 이제부터 신규로 문서 사이트를 구축하면서 AI 에이전트의 참조까지 고려한다면 Blume, 라는 식으로 구분될 것 같습니다.

마침 직전에 Zensical을 다루고 있었기에, zensical new로 생성된 Markdown을 그대로 Blume의 docs/에 두고 빌드할 수 있는지 시험해 보았습니다.

순수한 Markdown으로만 작성된 페이지(제목, 리스트, 표, 코드 블록 등)는 프론트매터(Frontmatter)를 title로 바꾸는 것만으로 그대로 빌드가 통과되었고, 라우팅(Routing)도 자동으로 /markdown/으로 인식되었습니다. 표준적인 Markdown 범위 내라면, 파일을 옮겨오는 것만으로도 충분하다는 인상입니다.

반면, !!! note와 같은 어드모니션(Admonition)이나 === "Python"과 같은 콘텐츠 탭 등 MkDocs(PyMdown Extensions) 고유의 표기법은 Blume 측에서 순조롭게 빌드되지 않았습니다. Blume는 MDX 기반이므로, 이것들은 <Note>나 <Tabs>와 같은 MDX 컴포넌트로 다시 작성해야 합니다.

ERROR Build failed with 1 error:
[plugin @mdx-js/rolldown] .../features-test.mdx
MDXError: Could not parse expression with oxc: Expected , or ) but found : (mdx-jsx:unexpected-character)

어드모니션뿐이라면 몰라도, 콘텐츠 탭, 각주, 수식, 아이콘 표기법까지 페이지 전체에 흩어져 있다면 페이지마다 일일이 손으로 다시 쓰는 것은 꽤나 고된 작업이 될 것 같습니다. 페이지 수가 많은 실제 사이트를 통째로 이행하려면, 꾸준한 변환 작업이 필요할 것이라고 각오해 두는 편이 좋을 것 같습니다.

그렇다고는 해도, 변환 규칙 자체는 「!!! note는 <Note>」, 「=== "Python"은 <Tabs> + <Tab>」와 같이 기계적으로 정의할 수 있는 것입니다. 지난번 Zensical 기사에서 만들었던 zensical-skills처럼, Blume 측의 MDX 컴포넌트 사양을 에이전트 스킬(Agent Skill)로 제공해 둔다면, AI 코딩 에이전트에게 변환 작업 자체를 맡길 수 있을 것입니다. 「MkDocs 표기법 → Blume의 MDX 컴포넌트」라는 대응표만 스킬(Skill)화 해둔다면, 대량의 페이지가 있더라도 사람이 일일이 하나씩 다시 쓸 필요는 없어질 것 같다는 느낌을 받았습니다.

실제로 사용해 본 소감으로는,

• npx blume init부터 npm run build까지 몇 분 만에 셋업이 완료되는 간편함
• 단 1페이지뿐인 최소 구성에서도 llms.txt나 agent-readability.json이 자동 생성되는, AI 전제 설계 사상
• blume.config.ts를 TypeScript로 작성할 수 있어 에디터의 타입 보완(Type Completion)이 그대로 적용됨
• blume doctor

와 같은 헬스 체크 (Health Check) 명령어가 처음부터 준비되어 있습니다. - MkDocs 계열 도구로부터의 이행은, 일반적인 Markdown은 그대로 유용할 수 있지만, admonition이나 탭(Tab) 등의 독자적인 표기법은 페이지 수가 많을 경우 꾸준한 재작성이 필요할 것으로 보입니다. 다만 변환 규칙 자체는 기계적으로 정의할 수 있으므로, Agent Skill화하여 AI 에이전트에게 맡긴다면 현실적으로 운영이 가능할 것 같다는 인상이었습니다. 문서 사이트가 '인간을 위한 웹 페이지'인 동시에 'AI 에이전트가 읽어들이는 지식 소스 (Knowledge Source)'이기도 하다는 전제에 입각한 도구 설계는, 향후 문서 도구 전반의 트렌드가 될 것이라고 느꼈습니다.