save-markdown

웹 페이지와 문서를 AI가 소비하기 쉬운 깔끔한 Markdown으로 변환하는 CLI 도구.

어떻게 작동하나요?

1. Firecrawl로 웹 페이지를 Markdown으로 변환
2. MarkItDown으로 PDF/Office 문서를 Markdown으로 변환
3. LLM(Gemini)으로 광고, 네비게이션 등 불필요한 요소 제거 (선택)
4. URL 경로 기반으로 깔끔한 파일명 자동 생성 (예: docs/guide → docs-guide.md)

---

📄 지원 파일 형식

URL뿐만 아니라 다양한 로컬 파일도 변환 가능합니다:

카테고리	확장자
Office 문서	.docx, .doc, .pptx, .xlsx, .xls
PDF	.pdf
이미지	.jpg, .png (OCR/비전 모델 필요)
오디오	.wav, .mp3 (음성 인식)
웹/텍스트	.html, .htm, .txt, .md
데이터	.csv, .json, .xml
압축 파일	.zip (내부 파일 순회)

💡 예시: markdown report.pdf, markdown presentation.pptx, markdown data.xlsx

---

⚡ 빠른 시작 (30초)

uv만 있으면 끝! Python 환경 설정 필요 없이 바로 설치됩니다.

# 1. uv 설치 (없다면)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 도구 설치
uv tool install git+https://github.com/opgginc/save-markdown.git

# 3. 바로 사용
markdown https://example.com

처음 실행 시 API 키 설정을 안내받습니다. 이후에는 바로 사용 가능!

업데이트

# 최신 버전으로 업데이트
uv tool upgrade save-markdown

---

기능

기능	설명
웹 스크래핑	Firecrawl로 URL을 Markdown으로 변환
콘텐츠 정제	LLM으로 네비게이션, 광고 등 불필요한 요소 제거
이미지 변환	비전 모델로 이미지를 텍스트 설명으로 변환
파일 처리	PDF, Office 문서 변환 (내장)
인터랙티브 모드	단계별 처리 옵션 선택

사용법

# URL 다운로드 (URL 경로 기반으로 자동 파일명 생성)
markdown https://example.com/docs/getting-started
# → docs-getting-started.md 로 저장

# 로컬 파일 처리
markdown document.pdf
# → document.md 로 저장

# 출력 파일명 지정
markdown https://example.com -o output.md

# 비대화형 + 정제
markdown https://example.com --no-interactive --sanitize

# 이미지를 텍스트로 변환
markdown https://example.com --image-convert

💡 자동 파일명 생성

출력 파일명을 지정하지 않으면 입력 소스를 기반으로 깔끔한 파일명이 자동 생성됩니다:

• URL: 도메인 제외, 경로만 사용 (docs/api-reference → docs-api-reference.md)
• 파일: 원본 파일명 유지 (document.pdf → document.md)
• 중복 방지: 이미 파일이 있으면 -2, -3 등 자동 추가

설정

API 키는 ~/.opgg/markdown/config.env에 저장됩니다:

OPENROUTER_API_KEY=sk-or-...
FIRECRAWL_API_KEY=fc-...

API 키 발급

서비스	용도	링크
OpenRouter	LLM 정제	openrouter.ai/keys
Firecrawl	웹 스크래핑	firecrawl.dev (무료 티어 있음)

---

개발

# 클론 및 설치
git clone https://github.com/opgginc/save-markdown.git
cd save-markdown
uv sync --extra dev

# 린팅
uv run ruff check src/
uv run mypy src/

# 테스트
uv run pytest

AI 에이전트 코딩 환경 설정은 README-ai-ready.md 참고.

프로젝트 구조

src/save_markdown/
├── main.py          # CLI 진입점
├── config.py        # 설정 관리
├── firecrawl.py     # 웹 스크래핑
├── sanitize.py      # LLM 정제
├── image_convert.py # 이미지→텍스트
├── markitdown.py    # PDF/Office 변환
└── utils.py         # 파일명 유틸리티

기여

1. 레포 클론 후 새 브랜치 생성
2. AGENTS.md의 스타일 가이드 따르기
3. uv run ruff check src/ && uv run mypy src/ 통과 확인
4. main 브랜치로 PR 생성

커밋 메시지 형식:

feat: 새 기능 추가
fix: 버그 수정
chore: 의존성 업데이트
docs: 문서 업데이트

링크

• OpenRouter Docs
• Firecrawl Docs
• Typer Docs

라이선스

MIT