Defuddle - 웹 페이지에서 본문만 깔끔하게 추출하는 오픈소스 라이브러리

개요

웹 페이지에서 본문 콘텐츠만 깔끔하게 뽑아내고 싶은 적이 있는가? 광고, 사이드바, 헤더, 푸터 같은 불필요한 요소를 제거하고 핵심 내용만 추출하는 것은 생각보다 까다로운 작업이다. Defuddle은 바로 이 문제를 해결하기 위해 만들어진 오픈소스 JavaScript 라이브러리다. 웹 페이지의 HTML을 받아서 본문만 추출하고, 원한다면 마크다운으로도 변환해준다.

왜 Defuddle을 만들었나

Defuddle의 개발자 Steph Ango(kepano)는 Obsidian Web Clipper를 만들면서 이 프로젝트를 시작했다. 기존에 널리 쓰이던 Mozilla의 Readability.js는 웹 페이지 본문 추출의 사실상 표준이었지만, 몇 가지 한계가 있었다.

• 너무 공격적인 제거: 확실하지 않은 요소도 과감하게 삭제해서 본문 일부가 사라지는 경우가 있었다
• 복잡한 요소 처리 미흡: 수학 수식(MathJax/KaTeX), 코드 블록의 구문 강조, 각주 등 기술 문서에서 흔한 요소를 제대로 처리하지 못했다
• 마크다운 변환 비최적화: HTML 출력이 마크다운 변환 도구(Turndown 등)에 넘기기에 깔끔하지 않았다
• 업데이트 정체: 프로젝트 관리가 활발하지 않아 현대 웹 환경 변화에 대응이 느렸다

Defuddle은 이런 문제를 해결하면서, 특히 마크다운 워크플로우에 최적화된 깔끔한 출력을 목표로 설계되었다.

어떻게 동작하는가

Defuddle의 내부 동작은 크게 3단계 파이프라인으로 구성된다.

1단계: 추출(Extraction)

사이트별 전용 추출기(extractor)가 있는 경우 해당 추출기를 사용하고, 없으면 휴리스틱 기반 범용 알고리즘으로 본문을 찾아낸다. Defuddle은 다양한 플랫폼에 대한 전용 추출기를 내장하고 있다.

• AI 서비스: ChatGPT, Claude, Gemini, Grok
• 소셜 플랫폼: Reddit, Hacker News, X/Twitter
• 개발 플랫폼: GitHub, YouTube

이 전용 추출기들은 해당 사이트의 DOM 구조를 정확히 알고 있어서 추측 없이 본문을 찾아낸다.

2단계: 표준화(Standardization)

추출된 HTML을 일관된 형식으로 정규화한다. 이 단계가 Defuddle의 핵심 차별점이다.

• 코드 블록: 줄 번호와 구문 강조 스타일을 제거하고, 프로그래밍 언어 정보만 data-lang 속성으로 보존한다
• 수학 수식: MathJax, KaTeX, MathML을 감지해서 표준 <math data-latex="..."> 형식으로 통일한다
• 각주: 다양한 각주 패턴을 마크다운의 [^1] 문법과 호환되는 표준 형식으로 변환한다
• 제목 태그: H1을 H2로 변환하고, 페이지 제목과 중복되는 첫 번째 제목은 제거한다
• 콜아웃: GitHub 알림, Obsidian, Bootstrap 등 다양한 형식을 통일된 data-callout 속성으로 표준화한다

3단계: 점수화 및 정리(Scoring & Cleanup)

페이지의 모바일 스타일시트를 분석해서 불필요한 요소를 추가로 식별하고, 저점수 블록을 제거하는 최종 정리를 수행한다.

주요 특징

Readability.js 대비 장점

• 관대한 처리: 확실하지 않은 요소를 무조건 삭제하지 않고 보존하는 방향으로 동작한다
• 모바일 스타일 활용: 페이지의 모바일 CSS를 분석해서 불필요한 요소를 판별하는 독자적인 기법을 사용한다
• 풍부한 메타데이터: schema.org 데이터를 포함한 광범위한 메타데이터를 추출한다
• 다중 패스 감지: 첫 시도에서 콘텐츠를 찾지 못하면 다른 방법으로 재시도하는 복구 메커니즘이 있다

3가지 번들 제공

용도에 따라 세 가지 번들 중 선택해서 사용할 수 있다.

• Core (defuddle): 브라우저용, 외부 의존성 없음. 가장 가벼움
• Full (defuddle/full): 수학 수식 파싱과 마크다운 변환 포함
• Node.js (defuddle/node): 서버 환경용, linkedom/jsdom 등과 함께 사용

풍부한 반환 데이터

파싱 결과에는 본문 HTML/마크다운 외에도 제목, 저자, 설명, 도메인, 대표 이미지, 파비콘, 언어, 발행일, 단어 수, 파싱 소요 시간, schema.org 데이터, 메타 태그 등 다양한 메타데이터가 포함된다.

YouTube 트랜스크립트 지원

YouTube URL을 넘기면 타임스탬프, 챕터, 화자 구분이 포함된 마크다운 트랜스크립트를 반환하는 기능도 있다.

사용 방법

설치

npm install defuddle

Node.js 환경에서는 DOM 구현체도 함께 설치한다.

npm install linkedom

브라우저에서 사용

import { Defuddle } from 'defuddle';

const defuddle = new Defuddle(document);
const result = defuddle.parse();

console.log(result.title);    // 페이지 제목
console.log(result.content);  // 정리된 본문 HTML

Node.js에서 사용

import { parseHTML } from 'linkedom';
import { Defuddle } from 'defuddle/node';

const { document } = parseHTML(html);
const result = await Defuddle(document, 'https://example.com');

console.log(result.content);  // 정리된 본문

마크다운으로 변환

import { Defuddle } from 'defuddle/full';

const defuddle = new Defuddle(document, { markdown: true });
const result = defuddle.parse();

console.log(result.content);  // 마크다운 형식 본문

CLI로 사용

설치 없이 바로 사용할 수도 있다.

# URL에서 마크다운 추출
npx defuddle parse https://example.com/article --markdown

# JSON 형식으로 메타데이터 포함 출력
npx defuddle parse https://example.com/article --json

# 특정 속성만 추출
npx defuddle parse page.html --property title

defuddle.md 웹 서비스

URL 앞에 defuddle.md/를 붙이면 별도 설치 없이 어디서든 웹 페이지의 마크다운 본문을 얻을 수 있다. curl로도 사용 가능하다.

주요 설정 옵션

Defuddle은 다양한 옵션으로 동작을 세밀하게 제어할 수 있다.

• markdown (boolean): 마크다운 변환 여부 (기본값: false)
• removeHiddenElements (boolean): CSS로 숨겨진 요소 제거 (기본값: true)
• removeLowScoring (boolean): 저점수 비콘텐츠 블록 제거 (기본값: true)
• removeSmallImages (boolean): 아이콘/트래킹 픽셀 제거 (기본값: true)
• standardize (boolean): HTML 구조 표준화 (기본값: true)
• contentSelector (string): 자동 감지 대신 특정 CSS 셀렉터로 본문 영역 지정
• debug (boolean): 디버그 모드 활성화 (기본값: false)

디버그 모드에서는 제거된 요소에 대한 상세 정보를 확인할 수 있어, 추출 결과가 기대와 다를 때 원인을 파악하기 좋다.

활용 사례

• 노트 앱 웹 클리퍼: Obsidian Web Clipper가 대표적인 사용 예다
• AI/RAG 파이프라인: LLM에 웹 콘텐츠를 입력할 때 노이즈를 제거한 깔끔한 텍스트를 만들 수 있다
• Read It Later 서비스: 나중에 읽기 앱에서 깔끔한 읽기 뷰를 제공할 수 있다
• MCP 서버: defuddle-fetch-mcp-server처럼 AI 에이전트가 웹 콘텐츠를 깔끔하게 가져오는 데 활용된다

마무리

Defuddle은 Readability.js의 한계를 극복하면서 마크다운 워크플로우에 최적화된 웹 콘텐츠 추출 도구다. 사이트별 전용 추출기, 3단계 파이프라인, 풍부한 메타데이터 추출이라는 탄탄한 설계를 갖추고 있다. 특히 AI 시대에 LLM 입력용 콘텐츠 정제 도구로서의 가치도 크다. 아직 개발 진행 중인 프로젝트이지만, GitHub에서 5,500개 이상의 스타를 받으며 활발하게 성장하고 있다.

---

참고 자료

• Defuddle GitHub 저장소
• Defuddle README
• kepano의 Defuddle 소개 트윗
• Hacker News 토론: Show HN - Defuddle
• Defuddle: The Next Generation of Web Content Extraction

이 글은 Claude Code를 활용하여 작성되었습니다.