AI-Ready 마크다운을 Symfony 앱에서 제공하기 🔥

Source: Dev.to

소개

AI 에이전트는 인간처럼 웹사이트를 읽지 않습니다.
Tailwind나 기타 CSS 클래스, 내비게이션 메뉴, JavaScript를 무시합니다.
그들이 원하는 것은 깔끔하고 구조화된 콘텐츠입니다:

• 명확한 헤딩
• 최소한의 마크업
• 프레젠테이션 잡음 없는 콘텐츠

ChatGPT, Claude, Perplexity, 그리고 자동 크롤러와 같은 도구가 점점 더 많이 웹을 탐색하면서, 원시 HTML을 제공하는 것은 비효율적이 됩니다. HTML에는 레이아웃 잡음—헤더, 푸터, 스크립트, 스타일, 쿠키 배너—이 포함되어 있어 토큰을 낭비하고 시맨틱 명확성을 떨어뜨립니다.

해결책: symfony‑markdown‑response‑bundle – 요청이 있을 때만 기존 HTML 응답을 Markdown으로 투명하게 변환하는 경량 Symfony 번들.

• GitHub:
• Packagist:

중복된 라우트도, 별도의 Markdown 컨트롤러도, 추가 유지보수도 없습니다.

이 번들의 기능

symfony-markdown-response-bundle 은 Symfony 응답을 가로채어, 적절할 경우:

1. 요청이 Markdown을 선호하는지 감지합니다.
2. HTML 출력에서 레이아웃 잡음을 제거합니다.
3. 정제된 HTML을 Markdown으로 변환합니다.
4. text/markdown 을 반환하고 text/html 은 반환하지 않습니다.

이 모든 과정은 투명하게 이루어지며, 컨트롤러 코드는 그대로 유지됩니다.

변환 백엔드

로컬 (기본)

• league/html-to-markdown 를 사용합니다.
• 변환은 외부 의존성 없이 프로세스 내에서 수행됩니다.

Cloudflare

변환 작업을 Cloudflare Workers AI 엔드포인트에 위임합니다.

# config/packages/symfony_markdown_response.yaml
symfony_markdown_response:
    driver: cloudflare
    cloudflare_endpoint: 'https://your-worker.example.workers.dev/to-markdown'

• symfony/http-client 가 필요합니다.
• HTML을 워커 엔드포인트에 POST하고, 응답 본문을 Markdown으로 반환합니다.

캐싱

변환된 Markdown 은 기본적으로 PSR‑6 캐시 풀을 사용해 캐시됩니다.

• Cache key: 전처리된 HTML의 xxh3 해시
• Default TTL: 3600 초

캐시 해결 순서

1. cache_service (설정된 경우)
2. cache.app
3. cache.system

캐시 비활성화

symfony_markdown_response:
    cache_enabled: false

사용 예시

use Soleinjast\MarkdownResponseBundle\Attribute\ProvideMarkdownResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/about')]
#[ProvideMarkdownResponse(enabled: true)]
public function about(): Response
{
    return $this->render('about.html.twig');
}

감지 규칙

다음 조건 중 하나라도 만족하면 번들은 Markdown 을 제공합니다:

• Accept: text/markdown 헤더
• URL 접미사 .md (예: /about.md)
• 알려진 AI 사용자 에이전트 (예: GPTBot, ClaudeBot, ChatGPT-User)

일반 브라우저 트래픽은 계속해서 HTML 을 받습니다.

설치

composer require soleinjast/symfony-markdown-response-bundle

그런 다음 Symfony 프로젝트에서 번들을 활성화합니다 (Symfony Flex 가 보통 자동으로 수행합니다) 그리고 Markdown 으로 노출하고 싶은 라우트에 어노테이션을 추가합니다.

왜 중요한가

20년 넘게 우리는 브라우저를 위해 웹을 최적화해 왔습니다; 이제는 읽고 추론하는 기계들을 위해서도 최적화가 필요합니다. 레이아웃 래퍼가 포함된 전체 HTML 을 제공하면 토큰 사용량이 늘어나고 신호 품질이 낮아집니다. Markdown 은:

• 헤딩과 계층 구조를 보존합니다.
• 단락을 그대로 유지합니다.
• 프레젠테이션 잡음을 제거합니다.
• 시맨틱 명확성을 향상시킵니다.
• 훨씬 가볍습니다.

애플리케이션이 이미 의미 있는 HTML 을 생성한다면, 기계가 가장 잘 이해하는 형식인 Markdown 으로 소비하게 하세요. symfony-markdown-response-bundle 은 그 격차를 깨끗하고 투명하게, 중복 없이 메워줍니다.