defuddle 살펴보기: 어떤 웹페이지든 깔끔한 Markdown으로 추출하는 오픈소스

웹페이지에는 본문 외에 주변 요소가 많이 붙어 있습니다.
필요한 것은 본문인데, 실제 페이지에는 댓글, 사이드바, 추천 기사, 광고, 헤더, 푸터가 함께 있습니다.

이 페이지를 LLM에 넣거나 Obsidian에 저장하거나 Markdown으로 정리하려면 주변 요소를 먼저 걷어내야 합니다.
페이지를 그대로 긁어 오는 크롤러로는 부족하고, 본문만 읽기 좋은 형태로 정제하는 도구가 필요합니다.

GeekNews에 소개된 defuddle은 이 문제를 다루는 오픈소스입니다.
웹페이지를 Markdown으로 바꾸는 기능 외에도, 웹 문서에서 본문을 추려내고 후처리하기 좋은 구조로 바꾸는 콘텐츠 파서 역할을 합니다.

defuddle은 무엇인가요?

defuddle은 웹페이지에서 불필요한 주변 요소를 제거하고 핵심 본문만 추출해 HTML 또는 Markdown으로 변환하는 도구입니다.

주요 기능은 다음과 같습니다.

댓글, 사이드바, 헤더, 푸터 제거
본문 중심 콘텐츠 추출
HTML / Markdown 출력 지원
각주, 수식, 코드 블록 같은 구조화 요소 처리
schema.org 기반 메타데이터 추출
CLI를 통한 URL/HTML 직접 파싱 지원

defuddle은 페이지 내용을 읽기용·저장용·후처리용으로 적합한 형태로 정제합니다.

프로젝트는 아직 실험·진행 중(WIP) 단계입니다. 사이트마다 결과가 달라질 수 있으며, 자세한 내용은 아래 “주의”에 적었습니다.

설치 방법

CLI만 쓴다면 전역 설치와 npx로 매번 실행 중 하나를 고릅니다.

CLI만 사용할 때

npm install -g defuddle

설치 후에는 npx 없이 defuddle parse <URL 또는 파일> ... 형태로 실행합니다.

전역 설치 없이 한 번만 실행하려면 다음 명령을 씁니다.

npx defuddle parse https://example.com/article

Node.js 프로젝트에서 라이브러리로 쓸 때

npm install defuddle

defuddle/node는 DOM 구현이 필요합니다. linkedom 또는 jsdom을 함께 설치합니다.

npm install linkedom
# 또는
npm install jsdom

ES 모듈로 defuddle/node를 import하려면 package.json에 "type": "module"이 필요합니다(공식 README 기준).

CLI 사용법

Defuddle CLI는 parse 서브커맨드 뒤에 URL 또는 로컬 HTML 경로를 받습니다. 기본 출력은 정제된 HTML입니다. Markdown·JSON·특정 메타 필드 추출은 플래그로 지정합니다.

자주 쓰는 예시

# URL 파싱 (표준 출력)
npx defuddle parse https://example.com/article

# 로컬 HTML 파일
npx defuddle parse ./article.html

# Markdown으로 출력 (--markdown, -m, --md 동일 계열)
npx defuddle parse https://example.com/article --markdown

# JSON(메타데이터 + 본문 등)
npx defuddle parse ./page.html --json

# 특정 속성만 (예: 제목)
npx defuddle parse ./page.html --property title

# 파일로 저장
npx defuddle parse ./page.html --output result.md

CLI 옵션 요약

옵션	별칭	설명
`--output <path>`	`-o`	표준 출력 대신 파일로 기록
`--markdown`	`-m`	본문을 Markdown으로
`--md`		`--markdown` 별칭
`--json`	`-j`	메타데이터와 콘텐츠를 JSON으로
`--property <name>`	`-p`	`title`, `description`, `domain` 등 특정 필드만
`--debug`		디버그 정보·로그 활성화
`--lang <코드>`	`-l`	선호 언어(BCP 47, 예: `en`, `ja`)

브라우저·Node API로 Defuddle 인스턴스를 만들어 파싱하는 방법은 공식 README ↗의 Usage 절에 있습니다.

웹 콘텐츠를 다시 쓰려면 잡음을 걷어내야 합니다

웹페이지는 사람만 읽지 않습니다.
웹 콘텐츠는 다음 용도로 다시 쓰입니다.

Obsidian 같은 노트 앱에 저장
LLM 입력용 컨텍스트로 정리
RAG 파이프라인에 넣기
기사나 문서를 아카이빙하기
Markdown 기반 지식베이스로 관리하기

이 과정에서 본문 외 잡음이 문제가 됩니다.

예를 들어 기사 하나를 가져오면 다음 요소가 함께 따라옵니다.

관련 기사 목록
공유 버튼
댓글 영역
추천 콘텐츠
사이트 공통 내비게이션
광고 박스
저작권 문구

defuddle은 이런 요소를 걷어내고 본문만 깨끗하게 가져오는 것을 목표로 합니다.

Mozilla Readability의 대안으로 설계됐습니다

프로젝트 소개에 따르면 defuddle은 Mozilla Readability의 대안으로 설계됐습니다.

Readability는 오랫동안 웹페이지 본문 추출 도구의 대표였습니다.
하지만 사이트마다 결과 편차가 있고, 필요한 메타데이터나 구조가 항상 나오지는 않습니다.

defuddle은 다음 방식을 택합니다.

더 유연한 처리
불확실할 때 과도하게 잘라내지 않음
더 일관된 HTML/Markdown 출력
후처리에 유리한 구조화 결과 제공

두 방식을 비교하면 다음과 같습니다.

항목	전통적인 본문 추출기	defuddle
목표	읽기용 본문 추출	읽기 + 저장 + 후처리 친화적 추출
출력	주로 정제된 본문 HTML	HTML + Markdown
메타데이터	제한적일 수 있음	schema.org 포함 더 풍부한 추출
활용성	브라우저 읽기 보기 느낌	노트, LLM, 파이프라인 활용에 적합

동작 흐름

구현 세부를 몰라도, 개념적으로는 아래 파이프라인으로 이해할 수 있습니다.
다이어그램은 위에서 아래로 읽습니다.

flowchart TB
    subgraph SRC["입력"]
        A["URL 또는 HTML 원문"]
    end

    subgraph CORE["Defuddle 처리"]
        direction TB
        B["본문 후보 분석"]
        C["불필요 요소 제거"]
        D["핵심 본문 정제"]
        E["메타데이터·구조 보존"]
    end

    subgraph DST["출력"]
        F["정제 HTML 또는 Markdown"]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

이 흐름에는 두 가지 특징이 있습니다.

첫째, 페이지에서 무엇을 덜어낼지 판단합니다.
둘째, 결과를 평문 텍스트로 만들지 않고 후처리 가능한 구조를 유지합니다.

defuddle은 각주, 수식, 코드 블록 같은 요소도 처리합니다.
개발 문서나 기술 글에서 이런 요소가 깨지면 추출 결과를 쓰기 어렵습니다.

모바일 스타일을 분석해 불필요 요소를 찾습니다

defuddle은 모바일 스타일을 분석해 불필요 요소를 감지합니다.

HTML 트리만 훑어서는 본문을 정확히 찾기 어려운 웹페이지가 많습니다.
사이트마다 반응형 구조가 다르고, 데스크톱과 모바일에서 같은 DOM 요소의 비중이 다르게 보이기도 합니다.

defuddle은 스타일 정보를 함께 보고 실제로 읽히는 문서 구조를 찾습니다.

Tip 본문 추출은 “무엇이 읽을 가치가 있는 콘텐츠인가”를 판별하는 문제입니다. 추출 결과가 불안정하다면 레이아웃과 스타일 힌트도 함께 쓰는 도구인지 확인합니다.

유튜브 대화를 화자별로 추출합니다

소개에 따르면 0.12.0부터 유튜브 영상 대화를 화자별로 분리해 추출할 수 있습니다.

영상 내용을 텍스트로 뽑으면 보통 자막 한 덩어리가 됩니다.
화자 단위로 나뉘면 다음 작업이 쉬워집니다.

인터뷰 정리
회의/대담 요약
영상 내용을 노트화
대화 흐름 분석
LLM 요약 품질 개선

AI 워크플로우에서 “누가 말했는가” 정보가 필요하다면 이 기능을 씁니다.

CLI가 주는 이점

CLI가 있으면 다음 작업이 쉬워집니다.

터미널에서 URL·로컬 HTML을 바로 파싱
셸 스크립트·CI와 연결한 배치 처리
LLM·RAG·노트 앱 파이프라인에 붙이기
에이전트가 “웹 한 장만 깔끔히” 가져가게 만들기

표준 입출력과 파일 경로로 연결되는 도구는 브라우저 확장만 있는 도구보다 자동화에 붙이기 쉽습니다.

주의 저장소는 아직 **진행 중인 프로젝트**라고 안내합니다. 본문 추출은 사이트 구조 변화에 민감합니다. 특정 사이트에서 잘 되던 결과가 레이아웃 변경 후 달라질 수 있습니다. 파이프라인에 넣는다면 예외 처리와 fallback 전략을 함께 둡니다.

어디에 맞을까

제가 보기에 defuddle은 다음 용도에 맞습니다.

1. Obsidian / 개인 지식 관리

defuddle은 Obsidian Web Clipper용으로 개발됐습니다. 저장용 Markdown 추출에 맞습니다.

2. LLM 입력 전처리

웹페이지를 그대로 넣지 않고 본문만 정리해 넣으면 토큰 낭비가 줄고 답변 품질도 좋아질 수 있습니다.

3. RAG / 문서 파이프라인

HTML 원문보다 정제된 Markdown이 chunking이나 후처리에 유리한 경우가 많습니다.

4. 읽기 아카이브

나중에 다시 읽거나 공유할 기사나 문서를 깔끔하게 보관할 수 있습니다.

마무리

웹 콘텐츠는 이제 사람, AI, 검색 인덱서, 노트 앱이 모두 읽습니다.
그래서 원문을 수집한 뒤 깨끗한 중간 형식으로 바꾸는 단계가 필요합니다. defuddle은 이 단계를 맡습니다.

defuddle은 웹 콘텐츠를 다시 쓸 수 있는 형태로 정제합니다. Readability 대안으로 설계됐고, Markdown 출력, 메타데이터 추출, 유튜브 화자 분리, CLI를 지원합니다.

Obsidian, LLM, RAG, 아카이빙 작업에서 웹페이지를 자주 가져온다면 defuddle을 전처리 단계에 넣어 볼 수 있습니다.

참고 자료

GeekNews 소개: https://news.hada.io/topic?id=27540 ↗
GitHub: https://github.com/kepano/defuddle ↗
Show HN: https://news.ycombinator.com/item?id=44067409 ↗