.md URL 사용법

특정 페이지만 마크다운으로 받고 싶을 때 사용합니다. URL 끝에 .md만 붙이면 같은 페이지를 깨끗한 마크다운으로 응답합니다.

기본 사용법

기존 페이지 URL 끝에 .md 확장자를 추가합니다. 36개 페이지 각각에 대해 1:1로 마크다운 버전이 매칭됩니다.

curl https://api-sandbox.sweetbook.com/docs/api/orders.md

주요 사용 케이스

• 특정 페이지만 필요할 때 — 전체 합본(llms-full.txt) 적재가 부담스럽거나, 한 페이지 내용만으로 충분한 작업
• 토큰 한도가 작은 도구 — 모델 컨텍스트 윈도우가 작은 환경에서는 페이지별 fetch가 효율적
• 문서 복사·공유 — 응답을 그대로 노션·이슈·README에 붙여넣기 좋음
• RAG 시스템 — 페이지 단위 임베딩 인덱싱

도구별 사용 예시

Cursor — 특정 페이지 컨텍스트 첨부

@https://api.sweetbook.com/docs/api/orders.md

이 문서 보고 주문 생성 + 부분 취소 처리 클라이언트 코드만 짜줘.

개발자가 직접 URL 조작

HTML 페이지를 읽다가 URL 끝에 .md만 추가하고 엔터를 누르면 같은 페이지가 마크다운으로 표시됩니다. 카피해서 다른 도구에 붙여넣기 좋습니다.

스크립트 자동화

#!/bin/bash
PAGES=("api/orders" "api/webhooks" "guides/scenario-pdf")
for slug in "${PAGES[@]}"; do
  curl -s "https://api-sandbox.sweetbook.com/docs/${slug}.md" \
    -o "docs/${slug//\//-}.md"
done

AGENT INSTRUCTIONS — AI 가드 메모

일부 페이지는 .md 응답 상단에 AI 전용 가드 메모가 HTML 주석으로 포함됩니다. HTML 페이지에서는 표시되지 않고, .md URL로 fetch할 때만 노출됩니다.

응답 모양

# Webhooks API

<!-- AGENT INSTRUCTIONS:
- secretKey 접두사는 `whsk_`. 최초 등록 시에만 전체 값이 응답에 반환되고, ...
- 서명은 HMAC-SHA256. 서명 페이로드는 `{timestamp}.{JSON body}` 형식, ...
- 전송 헤더 4종: `X-Webhook-Signature`(서명), `X-Webhook-Timestamp`(Unix epoch 초), ...
- 이벤트 타입은 페이지 본문 표의 9개만 사용. 임의 생성 금지.
-->

웹훅을 설정하여 주문 상태 변경 등의 이벤트를 실시간으로 수신하는 방법을 안내합니다.
...

왜 이런 방식인가

• 사람 본문 노이즈 제거 — "Bearer 접두사 필수" 같은 메모는 본문에서 충분히 설명되어 있으므로 중복. 하지만 AI에게는 명시적 가드가 환각·실수를 줄이는 데 효과적이라 마크다운 응답에만 끼워 넣음.
• HTML 페이지 깔끔함 유지 — 사람이 페이지를 읽을 때는 가드 메모가 보이지 않아 시각적 노이즈 없음.
• 자동 전파 — llms-full.txt 합본에도 그대로 포함되어 별도 작업 없이 한 번에 노출.

가드 메모가 포함된 페이지

현재 9개 페이지에 가드 메모가 적용되어 있습니다. 페이지 본문에서 충분히 설명되지 않은 미세한 규칙이나 AI가 자주 헷갈리는 포인트만 콕 짚어 보강합니다.

관련 문서

• AI 에이전트 지원 개요 — 3가지 산출물 한눈에 보기
• llms.txt · llms-full.txt 사용법 — 인덱스와 전체 합본