epub2md은(는) 무엇을 하나요?
EPUB를 Markdown으로 변환하며, TOC 및 스파인 인식 장 그룹화를 지원합니다.
이 기술을 사용해야 하는 경우
사용자가 다음과 같은 요청을 할 때 이 기술을 사용하세요:
- EPUB 파일(
.epub)을 제공하고 Markdown으로 변환해 달라고 요청할 때 - 전자책의 텍스트를 하나의 Markdown 파일로, 또는 장별로 하나의 Markdown 파일로 요청할 때
- 후속 처리(인덱싱, 임베딩, 번역, 리뷰)를 위해 EPUB를 장별로 분할하려 할 때
- EPUB의 구조(스파인, TOC, 장)를 검사해 달라고 요청할 때
PDF, Word 문서, 웹 페이지에는 이 기술을 사용하지 마세요. 대신 해당 형식에 맞는 도구를 사용하세요.
입력
- EPUB 파일 경로
- 선택적 출력 디렉토리 (기본값:
./output) - 선택적 모드:
single,chapters, 또는both(기본값:both) - 선택적 그룹화 방식:
toc,spine, 또는auto(기본값:auto)
출력
항상 생성되는 파일들 (출력 디렉토리 내):
book-extracted/— 원본 EPUB 파일의 압축 해제된 내용book-assets/— 책에서 참조하는 이미지 및 미디어 파일chapters/NN-slug.md— 장별 Markdown 파일chapters.json— 제목, 원본 파일, 앵커, 출력 경로가 포함된 장 매니페스트combined.html— 검사를 위해 연결된 장 HTMLbook.md— 전체 책을 하나의 Markdown 파일로metadata.json— 제목, 저자, 언어, 식별자, 출판사, EPUB 버전, 장 개수
실행 방법
이 기술은 scripts/run.sh 실행기를 제공하며, 이 실행기는 epub2md CLI를 찾아 모든 인수를 전달합니다. epub2md가 설치되어 있든 없든 작동합니다:
epub2md가PATH에 있으면 직접 사용합니다.- 그렇지 않고
epub2mdPython 패키지를 임포트할 수 있으면python3 -m epub2md를 사용합니다. - 그렇지 않으면 실행기는 자신 옆에 있는 소스 트리(
scripts/epub2md/)를 사용하므로 설치 단계 없이 새 클론에서 바로 작동합니다.
bash scripts/run.sh path/to/book.epub -o output/ --overwrite
반복 사용을 권장하는 방식: 패키지를 한 번 설치하세요.
pip install .
epub2md path/to/book.epub -o output/ --overwrite
고품질 변환을 위해 Pandoc을 설치하세요. epub2md는 PATH에서 Pandoc을 사용할 수 있을 때는 Pandoc을 사용하고, 그렇지 않으면 순수 Python 변환기로 대체합니다.
일반적인 사용법
하나의 Markdown 파일로 변환
bash scripts/run.sh book.epub -o out/ --mode single --overwrite
# 읽을 파일: out/book.md
TOC를 사용하여 장별 분할
bash scripts/run.sh book.epub -o out/ --mode chapters --group-by toc --overwrite
# 읽을 파일: out/chapters/NN-slug.md 및 out/chapters.json
스파인 기반 그룹화 강제
TOC가 없거나, 잘못되었거나, 신뢰할 수 없을 때 사용하세요.
bash scripts/run.sh book.epub -o out/ --group-by spine --overwrite
Python 라이브러리로 사용
from epub2md import convert
result = convert("book.epub", output_dir="out", mode="both", overwrite=True)
print(result.book_md)
print(len(result.chapters))
그룹화 로직
- TOC가 존재하는 경우, 기본
auto모드는 TOC를 사용합니다. 각 최상위 TOC 항목이 하나의 장이 됩니다. 장은 해당 항목의 시작 파일부터 다음 항목의 시작 파일까지 모든 스파인 문서를 포함합니다. 이렇게 하면 여러 XHTML 파일에 걸쳐 분할된 장을 다시 조합합니다. - TOC가 없으면 도구는 스파인으로 대체합니다. 각 스파인 문서가 하나의 장이 됩니다.
- 첫 번째 TOC 항목 이전에 스파인에 나타나는 전면부(front matter)는 하나의 "전면부" 장으로 그룹화됩니다.
오류 처리
container.xml또는 OPF가 없으면: 도구가 명확한 메시지와 함께 종료되며, EPUB가 유효하지 않습니다.- 잘못된 XHTML 조각: 관대 모드로 구문 분석합니다. 조각 변환에 실패하면 원시 HTML을 펜스 블록에 포함시켜 내용이 손실되지 않도록 합니다.
- 참조된 이미지 누락: 경고를 표시하고 Markdown 출력에 원래
src를 유지합니다. - Pandoc이 설치되지 않은 경우: 도구는 자동 모드에서 조용히
markdownify로 대체합니다.
참고 자료
references/spec.md— 전체 명세, 그룹화 알고리즘, 출력 레이아웃references/troubleshooting.md— 일반적인 EPUB 변환 문제에 대한 실용적인 해결 방법