Obsidian CEO Steph Ango(kepano)가 직접 만든 오픈소스 라이브러리가 개발자 커뮤니티를 뒤흔들고 있다. 이름은 Defuddle. 어떤 웹페이지 URL이든 마크다운(Markdown)으로 깔끔하게 추출해주는 도구다.
기존에 Firecrawl 같은 유료 서비스를 월 16 - 333달러씩 구독하며 웹 콘텐츠 추출을 처리하던 개발자들이 Defuddle 하나로 동일한 작업을 무료로 수행할 수 있게 됐다. 웹사이트(defuddle.md), CLI, curl, npm 패키지 등 다양한 방식으로 접근 가능하며, Claude Code Skill까지 공식 지원한다.
Defuddle 공식 사이트: https://defuddle.md/
Claude Code Skill: https://skills.sh/kepano/obsidian-skills/defuddle
이 글에서는 Defuddle의 핵심 기능, 기존 도구와의 비교, 실전 활용법, 그리고 AI 워크플로우에 통합하는 구체적인 방법까지 다룬다.
Defuddle이란 무엇인가
Defuddle은 웹페이지의 핵심 콘텐츠만 추출하여 깔끔한 HTML 또는 마크다운으로 변환하는 JavaScript 라이브러리다. 이름 자체가 웹페이지에서 불필요한 요소를 제거하고 쉽게 읽을 수 있게 만드는 것이라는 뜻의 동사형 신조어다.
Steph Ango는 Obsidian Web Clipper를 개발하면서 기존 Mozilla Readability의 한계를 체감했고, 이를 대체하기 위해 Defuddle을 만들었다. 광고, 사이드바, 헤더, 푸터, 댓글 영역 등 본문과 무관한 요소를 자동으로 제거하고, 코드 블록과 각주, 수학 수식까지 표준화된 포맷으로 정리해준다.
핵심적인 차별점은 세 가지다. 첫째, Mozilla Readability보다 관대한 추출 방식을 채택해 유용한 콘텐츠가 실수로 삭제되는 문제를 줄였다. 둘째, 페이지의 모바일 CSS 스타일을 분석하여 숨겨진 불필요 요소를 탐지한다. 셋째, Schema.org 데이터를 포함한 풍부한 메타데이터를 함께 추출한다.
Defuddle은 100% 규칙 기반(rule-based)으로 동작하며 AI 모델을 사용하지 않는다. 코드에서 Gemini, Claude 등의 이름이 보이는 것은 해당 사이트의 대화 내용을 추출하기 위한 사이트별 Extractor 규칙이다. 별도의 API 비용이 발생하지 않는다.
MIT 라이선스의 완전한 오픈소스
Defuddle은 MIT 라이선스로 공개되어 있으며, GitHub 저장소(kepano/defuddle)에서 전체 소스코드를 확인할 수 있다. 상업적 프로젝트에도 자유롭게 사용 가능하다. npm 패키지로도 배포되어 npm install defuddle 한 줄이면 프로젝트에 즉시 통합된다.
사용 방법 5가지와 실전 적용
Defuddle은 다양한 환경에서 유연하게 사용할 수 있도록 설계됐다. 개발자가 아니어도 웹 브라우저에서 바로 사용 가능하고, 고급 사용자라면 CLI와 API를 조합하여 자동화 파이프라인을 구축할 수 있다.
웹사이트에서 바로 사용하기
가장 간단한 방법이다. defuddle.md/ 뒤에 원하는 URL을 붙이면 해당 페이지의 마크다운 콘텐츠가 YAML frontmatter와 함께 반환된다. curl defuddle.md/stephango.com 이 한 줄이면 Steph Ango의 블로그 내용이 마크다운으로 출력된다. 별도의 설치나 인증 없이 브라우저 주소창에 직접 입력해도 작동한다.
CLI 명령줄 인터페이스
글로벌 설치 후 터미널에서 직접 실행할 수 있다. npm install -g defuddle 명령으로 설치하고, defuddle parse URL --md 형태로 실행하면 된다. --md 플래그로 마크다운 출력, --json 플래그로 메타데이터를 포함한 JSON 출력, -p title로 특정 속성만 추출하는 것이 가능하다. 파일 저장은 -o output.md 옵션을 추가하면 된다.
Node.js 라이브러리
HTML 문자열이나 JSDOM 인스턴스를 입력으로 받아 비동기로 처리한다. defuddle/node에서 Defuddle을 import하고, JSDOM과 함께 사용하면 된다. markdown: true 옵션을 추가하면 마크다운 형태로 결과를 받을 수 있다. package.json에 type: module 설정이 필요하다.
브라우저 확장 프로그램 및 북마클릿
Defuddle은 Obsidian Web Clipper의 핵심 엔진이기도 하다. 브라우저 확장 프로그램으로 사용하면 로그인이 필요한 페이지나 JavaScript로 렌더링되는 SPA 페이지에서도 콘텐츠를 추출할 수 있다. defuddle.md 사이트에서는 드래그-앤-드롭 북마클릿도 제공한다.
Claude Code Skill
Claude Code 사용자라면 공식 Defuddle Skill을 설치하여 AI 코딩 워크플로우에 직접 통합할 수 있다. 설치 후 defuddle, extract article, clean this page 같은 트리거 키워드로 자동 호출된다.
Claude Code Skill로 Defuddle을 사용하면 기존 WebFetch 대비 광고와 내비게이션 등의 불필요한 텍스트가 제거되어 토큰 사용량이 크게 절감된다. LLM에 웹 컨텍스트를 제공할 때 비용과 정확도 모두 개선된다.
| 사용 방법 | 설치 필요 | 적합한 사용자 | 출력 형식 |
|---|---|---|---|
| defuddle.md 웹사이트 | 없음 | 누구나 | Markdown + YAML |
| CLI | npm install -g | 개발자와 자동화 | Markdown, JSON, HTML |
| Node.js 라이브러리 | npm install | 백엔드 개발자 | 프로그래밍 방식 제어 |
| 브라우저 확장과 북마클릿 | 드래그 설치 | 일반 사용자 | Markdown |
| Claude Code Skill | Skill 등록 | AI 개발자 | Markdown |
Node.js 환경에서 사용할 때는 반드시 JSDOM 패키지도 함께 설치해야 한다. npm install defuddle jsdom 명령으로 동시에 설치하는 것을 권장한다.
Defuddle vs Firecrawl vs Mozilla Readability 핵심 비교
웹 콘텐츠를 마크다운으로 변환하는 도구는 여러 가지가 있다. 각각의 장점과 한계가 뚜렷하므로, 프로젝트 성격에 맞는 선택이 중요하다.
Defuddle vs Mozilla Readability
Mozilla Readability는 Firefox 리더 모드의 핵심 라이브러리로, 오랫동안 웹 콘텐츠 추출의 표준 역할을 해왔다. 하지만 개발자 커뮤니티에서는 유지보수 속도가 느려지고 있다는 지적이 꾸준히 나왔다.
Steph Ango는 Hacker News에서 직접 차이점을 설명했다. Readability는 메인 콘텐츠의 시작과 끝을 찾기 위해 블록을 테스트하는 방식이라 보수적으로 작동하며, 유용한 콘텐츠까지 제거하는 경향이 있다. 반면 Defuddle은 여러 번의 패스를 실행하고, 콘텐츠가 반환되지 않으면 결과를 확장하는 메커니즘을 갖추고 있다.
| 비교 항목 | Defuddle | Mozilla Readability |
|---|---|---|
| 추출 방식 | 다중 패스와 점진적 확장 | 단일 패스와 보수적 제거 |
| HTML 표준화 | 각주와 코드블록과 수식 통일 | 원본 DOM 유지 |
| 마크다운 변환 | 내장 Turndown 통합 | 별도 라이브러리 필요 |
| 모바일 CSS 감지 | 지원 | 미지원 |
| 메타데이터 추출 | Schema.org 포함 | 기본 메타만 추출 |
| 사이트별 Extractor | YouTube와 X와 Reddit 등 | 없음 |
| 라이선스 | MIT | Apache 2.0 |
Defuddle vs Firecrawl
Firecrawl은 AI 기반 웹 스크래핑 API 서비스로, 유료 구독 모델로 운영된다. 무료 플랜은 월 500 크레딧, Hobby 플랜은 월 16달러에 3000 크레딧, Standard 플랜은 월 83달러에 10만 크레딧, Growth 플랜은 월 333달러에 50만 크레딧으로 제공된다.
Defuddle은 무료이자 오픈소스다. 크레딧 제한이 없으며, 셀프 호스팅이 가능하다. 다만 Firecrawl이 제공하는 대규모 크롤링, 안티봇 우회, 구조화된 데이터 추출 같은 엔터프라이즈 기능은 Defuddle의 범위를 벗어난다.
| 비교 항목 | Defuddle | Firecrawl |
|---|---|---|
| 가격 | 무료 MIT 오픈소스 | 무료 500크레딧부터 월 333달러 |
| 마크다운 변환 | 핵심 기능 | 지원 |
| 대규모 크롤링 | 미지원 | 지원 |
| 안티봇 우회 | 미지원 | 지원 |
| AI 추출 | 미지원이며 규칙 기반 | 지원하며 토큰 기반 별도 과금 |
| 셀프 호스팅 | 가능 | 가능하며 오픈소스 버전 존재 |
| 설치 용이성 | npm install 한 줄 | API 키 발급 필요 |
단일 페이지의 콘텐츠를 마크다운으로 변환하는 용도라면 Defuddle이 최적의 선택이다. 수천 개 페이지를 크롤링하며 안티봇 프록시가 필요한 엔터프라이즈 수준의 작업이라면 Firecrawl이나 Crawl4AI를 병행하는 것이 현실적이다.
YouTube 트랜스크립트 기능의 현실적인 한계
2026년 3월 13일 Defuddle v0.12.0이 릴리스되면서 YouTube 트랜스크립트 추출 기능이 새롭게 추가됐다. Steph Ango는 X(구 Twitter)와 Bluesky에서 YouTube 링크를 defuddle.md에 붙여넣으면 타임스탬프와 챕터, 화자 분리(diarization)가 포함된 마크다운 트랜스크립트를 받을 수 있다고 발표했다.
하지만 실제 테스트 결과, 모든 유튜브 영상에서 트랜스크립트가 정상적으로 추출되지는 않았다. 일부 영상에서는 제목과 URL 정도의 기본 메타데이터만 반환되고 본문 트랜스크립트는 비어 있는 경우가 확인됐다.
이런 현상이 발생하는 원인은 여러 가지로 추정된다. 자막(캡션)이 비활성화된 영상, 자동 생성 자막이 아직 처리되지 않은 영상, 특정 언어의 영상에서 추출 로직이 아직 완성되지 않은 경우 등이다. v0.12.0은 릴리스된 지 하루도 안 된 매우 초기 단계의 기능이므로, 향후 업데이트를 통해 안정성이 개선될 가능성이 높다.
YouTube 트랜스크립트 기능은 v0.12.0에서 막 추가된 실험적 기능이다. 프로덕션 환경에서 유튜브 트랜스크립트 추출에 의존하는 워크플로우를 구축한다면, Defuddle의 결과가 빈 값인 경우를 대비한 폴백 로직을 반드시 마련해야 한다.
정상 작동하는 경우의 출력 형태
트랜스크립트가 정상적으로 추출될 때는 YAML frontmatter에 제목과 소스 URL, 언어, 설명 등의 메타데이터가 포함되고, 본문에 타임스탬프와 함께 텍스트가 마크다운으로 정리된다. 챕터가 있는 영상이라면 챕터 제목이 H2 헤딩으로 구분된다.
AI 워크플로우와 MCP 서버 통합 활용법
Defuddle은 AI 기반 리서치 워크플로우에서 특히 강력하다. 웹페이지 내용을 LLM에 컨텍스트로 전달할 때, 기존에는 광고와 내비게이션, 푸터 등의 불필요한 텍스트까지 함께 전달되어 토큰이 낭비됐다. Defuddle로 핵심 콘텐츠만 추출하면 토큰 사용량이 약 40 - 60% 절감되는 효과를 기대할 수 있다.
MCP 서버와 AI 에이전트 연동
Defuddle은 Model Context Protocol(MCP) 서버로도 활용 가능하다. defuddle-fetch-mcp-server라는 패키지가 이미 공개되어 있어, LLM 기반 AI 에이전트가 웹 콘텐츠를 구조화된 형태로 가져오는 파이프라인을 구축할 수 있다.
실제 활용 사례를 정리하면 다음과 같다.
RAG 파이프라인 구축: 웹페이지의 핵심 텍스트만 추출하여 벡터 DB에 저장하면, 광고와 내비게이션 등의 노이즈가 제거되어 검색 정확도가 향상된다.
리서치 자동화: Claude Code에서 Defuddle Skill을 활용하면, 특정 URL의 콘텐츠를 마크다운으로 가져와서 요약과 분석, 비교하는 작업을 한 번의 프롬프트로 처리할 수 있다.
지식 베이스 구축: Obsidian, LogSeq 등 마크다운 기반 노트 앱과 연동하여 웹에서 수집한 정보를 체계적으로 정리할 수 있다. Obsidian Web Clipper가 이미 Defuddle을 핵심 엔진으로 사용하고 있어 궁합이 뛰어나다.
Defuddle의 useAsync 옵션이 true(기본값)일 때, 로컬 HTML에서 콘텐츠를 추출하지 못하면 FxTwitter API 같은 서드파티 서비스를 폴백으로 호출할 수 있다. 프라이버시가 중요한 환경이라면 useAsync: false로 설정하여 외부 API 호출을 차단하는 것이 안전하다.
Defuddle 기술 아키텍처와 고급 옵션
Defuddle은 세 가지 번들로 제공된다. Core 번들은 브라우저용으로 의존성이 없다. Full 번들은 MathML-LaTeX 변환과 Turndown 기반 마크다운 변환을 포함한다. Node.js 번들은 JSDOM과 통합되어 서버 환경에 최적화되어 있다.
HTML 표준화 파이프라인
Defuddle의 진정한 강점은 단순한 콘텐츠 추출을 넘어 HTML을 표준화하는 파이프라인에 있다. 제목(Heading)의 경우, 본문 제목과 일치하는 첫 H1이나 H2를 자동 제거하고, 모든 H1을 H2로 변환한다. 앵커 링크가 포함된 헤딩은 순수 텍스트로 정리된다.
코드 블록은 라인 넘버와 구문 강조를 제거하되, 프로그래밍 언어 정보는 data-lang 속성과 language 클래스로 보존한다. 각주는 인라인 참조와 하단 각주 목록이 통일된 포맷으로 변환된다. MathJax와 KaTeX 수식은 표준 MathML로 변환되며, 원본 LaTeX 소스가 data-latex 속성에 보존된다.
디버그 모드 활용법
Defuddle이 특정 페이지에서 원하는 결과를 내지 못할 때, debug: true 옵션을 활성화하면 어떤 요소가 어떤 이유로 제거됐는지 상세 로그를 확인할 수 있다. result.debug.contentSelector로 선택된 메인 콘텐츠 영역의 CSS 셀렉터 경로를, result.debug.removals로 제거된 요소 목록을 확인한다.
파이프라인의 개별 단계를 비활성화하는 것도 가능하다. removeLowScoring: false로 콘텐츠 스코어링을 건너뛰거나, removeHiddenElements: false로 CSS 기반 숨김 요소 제거를 비활성화할 수 있다. contentSelector 옵션으로 자동 감지를 우회하고 특정 CSS 셀렉터를 직접 지정하는 것도 지원된다.
Defuddle이 반환하는 response 객체에는 parseTime(밀리초 단위 파싱 시간)과 wordCount(단어 수)가 포함되어 있어, 성능 모니터링과 콘텐츠 길이 기반 필터링에 활용할 수 있다.
Defuddle 도입 시 주의할 점과 한계
Defuddle은 강력한 도구이지만 만능은 아니다. 현재 진행 중인 프로젝트(work in progress)임을 공식 README에서 명시하고 있으며, 몇 가지 알려진 한계가 존재한다.
첫째, Chrome 확장 프로그램의 백그라운드 스크립트(서비스 워커)에서는 직접 실행이 어렵다. getComputedStyle 함수와 URL 생성자 등이 서비스 워커 환경에서 지원되지 않기 때문이다. 콘텐츠 스크립트에서 실행하거나 Node.js 서버를 경유하는 방식으로 우회해야 한다.
둘째, 자동화된 테스트 데이터셋이 아직 구축되지 않았다. Steph Ango는 현재 수동 테스트와 사용자 피드백에 의존하고 있다고 밝혔다. 테스트 프레임워크 추가는 향후 로드맵에 포함되어 있다.
셋째, 클라이언트 사이드 렌더링(CSR)만 지원하는 SPA 페이지에서는 콘텐츠 추출이 실패할 수 있다. 이 경우 useAsync: true 옵션으로 서드파티 API 폴백을 활용하거나, 브라우저 확장 프로그램을 통해 렌더링된 DOM에 직접 접근하는 방식이 필요하다.
넷째, v0.12.0에서 추가된 YouTube 트랜스크립트 기능은 아직 모든 영상에서 안정적으로 작동하지 않는다. 자막이 없거나 특정 조건의 영상에서는 빈 결과가 반환될 수 있으므로, 이 기능에 전적으로 의존하기보다는 보조 수단으로 활용하는 것이 현실적이다.
기존에 Firecrawl을 월 16 - 83달러에 구독하며 단일 페이지 마크다운 변환 용도로 사용해왔다면, Defuddle로 전환하는 것만으로 연간 192 - 996달러를 절감할 수 있다. 물론 대규모 크롤링이 필요한 경우에는 두 도구를 병행하는 전략이 현실적이다.
Defuddle은 Obsidian CEO가 자신의 제품에서 실제로 사용하기 위해 만든 도구다. Obsidian Web Clipper라는 실전 환경에서 검증된 코드 위에 세워져 있고, 마크다운 생태계에 대한 깊은 이해가 반영되어 있다. AI 시대에 웹 콘텐츠를 LLM이 소화할 수 있는 형태로 변환하는 일이 점점 중요해지는 지금, Defuddle은 그 핵심 인프라가 될 가능성이 높다.
지금 바로 터미널을 열고 npm install -g defuddle을 실행하거나, 브라우저에서 defuddle.md/ 뒤에 원하는 URL을 붙여 직접 체험해보자.