나는 Cloudflare의 “Markdown for Agents” 아이디어를 NGINX(Rust 모듈)에서 시도해봤다 — 초기 프로토타입

Source: Dev.to

소개

Cloudflare는 최근 Markdown for Agents 를 출시했습니다. 클라이언트가 Accept: text/markdown 헤더를 보내면, Cloudflare가 HTML을 가져와 Markdown 형태로 반환합니다.
이 아이디어에 영감을 받아, 자체 인프라에서 비슷한 작업을 수행할 수 있는 셀프‑호스팅 가능한 NGINX 동적 모듈을 만들었습니다. 이는 매우 초기 단계의 프로토타입으로, 워크플로를 체험하고 피드백을 공유하고자 하는 사람들을 위한 것입니다.

저장소:

작동 방식

• 애플리케이션 코드를 수정할 필요가 없습니다. 변환은 전적으로 리버스‑프록시 레이어에서 이루어집니다.
• 가장 적합한 경우: 문서, 블로그, 뉴스, 지식‑베이스 페이지.
• 부적합한 경우: API, 스트리밍 응답, 인증이 필요한 페이지(캐시를 신중히 다루는 경우 제외).

에이전트와 LLM 도구는 전체 HTML을 가져와 네비게이션, 푸터, 쿠키 배너, 레이아웃 마크업, 스크립트, 잡음이 많은 속성 등에 토큰을 낭비합니다. Markdown 변형을 사용하면 다운스트림 파싱 비용을 낮추고 예측 가능성을 높일 수 있습니다.

설치

# 모듈 설치
curl -sSL https://raw.githubusercontent.com/cnkang/nginx-markdown-for-agents/main/tools/install.sh | sudo bash

# NGINX 테스트 및 재로드
sudo nginx -t && sudo nginx -s reload

주의: 동적 모듈은 정확히 현재 사용 중인 NGINX 패치 버전(nginx -v)과 일치해야 합니다. 일치하는 빌드가 없을 경우 직접 모듈을 컴파일해야 할 수 있습니다.

Markdown 변형 확인

# Markdown 요청
curl -sD - -o /dev/null -H "Accept: text/markdown" http://localhost:8080/ | grep -iE 'content-type|vary'
# 예상 출력:
# content-type: text/markdown; charset=utf-8
# vary: Accept

HTML 변형 확인

curl -sD - -o /dev/null -H "Accept: text/html" http://localhost:8080/ | grep -i 'content-type'

샘플 요청

curl -s -H "Accept: text/markdown" http://localhost:8080/ | head -40

설정

먼저 작은 범위에서 시작해 하나의 라우트에만 필터를 활성화해 보세요.

load_module modules/ngx_http_markdown_filter_module.so;

http {
    markdown_filter off;

    server {
        listen 8080;

        location /docs/ {
            markdown_filter on;

            # 권장: 깨끗한 변환을 위해 업스트림 압축을 비활성화
            proxy_set_header Accept-Encoding "";

            proxy_pass http://backend;
        }
    }
}

실패 시 열기 (시도 단계에서 권장)

변환에 실패하면 원본 HTML이 반환됩니다:

markdown_on_error pass;

작업 제한

markdown_max_size 10m;
markdown_timeout 5s;

메트릭 엔드포인트 (localhost 전용)

location /markdown-metrics {
    markdown_metrics;
}

캐시 고려사항

NGINX 또는 CDN에서 캐시를 사용할 경우 Accept 헤더에 따라 변형이 구분되도록 설정하세요:

proxy_cache_key "$scheme$request_method$host$request_uri$http_accept";

주의 사항

• 특수한 경우가 존재합니다(이상한 HTML, 거대한 페이지, 특수 인코딩 등).
• 모듈은 HTML → Markdown 변환에만 초점을 맞추며(PDF나 임의 바이너리는 지원하지 않음)
• 캐시 설정에 주의가 필요합니다(변형 키 + 인증 인식 동작).

깨진 페이지, 매우 느린 페이지, 혹은 캐시 문제가 발생하면 다음 정보를 포함하여 이슈를 열어 주세요:

• 샘플 URL(또는 익명화된 HTML)
• nginx -v 출력
• 업스트림이 압축된 여부
• 앞단에 존재하는 캐시/CDN 여부

참고 자료

• Cloudflare 영감 – 블로그:
• Cloudflare 문서:
• 프로젝트 저장소: