한글 문서를 마크다운으로

분명 추출했는데 결과가 비어 있을 때

hwp5txt를 돌렸는데 오류 없이 빈 파일이 나옵니다. PDF를 열면 글자가 보이는데 복사가 되지 않습니다. 도구를 바꿔 가며 몇 번을 더 시도합니다.

이럴 때 원인이 도구가 아닌 경우가 많습니다. 실제 폴더의 문서 1,002개를 살펴보니 이런 파일들이 섞여 있었습니다.

겉보기	실제	개수
.hwp 파일	암호가 걸렸거나 깨진 파일	17
.hwp 파일	내려받다 끊겨 앞부분이 빈 파일	6
.xlsx 파일	엑셀이 만든 임시 잠금 파일	6
.pdf 파일	내려받기 실패 안내문이 저장된 것	3

32개가 문서가 아니었습니다. 여기에는 어떤 도구를 써도 열리지 않습니다. 먼저 알았다면 시도할 이유가 없었습니다.

스킬은 무엇을 하나요?

추출하기 전에 파일이 무엇인지부터 판정합니다.

확장자를 믿지 않고 파일의 첫 부분을 읽어 형식을 가릅니다. PDF는 글자 수를 재서 스캔인지 확인합니다. 그다음 형식에 맞는 방법을 고르고, 추출한 뒤에는 결과 길이로 성공 여부를 확인합니다.

뽑은 글을 그대로 쓰지 않고 정리까지 안내합니다. 옛 문서는 한자가 섞여 들어오고, 오래된 한글 파일은 추출 방법을 잘못 고르면 낱말이 전부 붙어 나옵니다. 둘 다 미리 알고 시작하는 편이 낫습니다.

그냥 변환 도구를 쓰는 것과 무엇이 다른가요?

변환 도구는 결과를 줍니다. 그 결과가 맞는지는 알려주지 않습니다.

이 스킬이 가진 판단 기준은 두 가지입니다.

성공했는지 종료 상태로 판단하지 않습니다. hwp5txt도 kordoc도 실패하고 정상 종료를 알립니다. 결과 길이를 재야 압니다. 100글자도 안 되면서 그림 표시만 남았다면, 본문이 그림으로 들어간 문서입니다.

확장자로 형식을 단정하지 않습니다. 앞의 표에 나온 32개가 그래서 생긴 일입니다.

어떤 순서로 진행되나요?

1단계. 폴더에 무엇이 있는지 판정합니다

파일마다 형식과 추출 방법, 주의할 점을 정리해 보여줍니다. 문서가 아닌 파일은 여기서 걸러집니다.

문서.hwp
  형식   HWP 5.0 (OLE2)
  방법   hwp5txt
  참고   본문이 그림으로 들어간 문서는 결과가 그림 표시만 남습니다.

보고서.pdf
  형식   PDF (스캔으로 보임, 122쪽)
  방법   쪽을 이미지로 만든 뒤 문자 인식
  참고   앞 80쪽에서 41자만 나왔습니다.

2단계. 형식에 맞는 방법으로 뽑습니다

HWP 5.0과 HWPX는 바로 뽑습니다. 옛 HWP 3.0은 변환을 거쳐야 하는데, 어느 경로로 변환하느냐에 따라 결과가 크게 갈립니다. 띄어쓰기를 지키는 쪽으로 안내합니다. 스캔 PDF는 쪽을 이미지로 만들어 문자 인식으로 넘깁니다.

3단계. 결과를 확인합니다

파일마다 글자 수를 기록합니다. 1,000자가 넘으면 본문이 들어온 것이고, 100자도 안 되면 다시 봐야 합니다. 기록해 두면 나중에 같은 폴더를 다시 훑을 때 두 번 처리하지 않습니다.

4단계. 뽑은 글을 정리합니다

한자가 섞여 들어왔다면 낱말 단위로 바꿉니다. 한 글자씩 바꾸면 앞뒤가 붙어 없던 낱말이 생깁니다. 파일 이름이 깨졌다면 어느 단계에서 깨졌는지 구분해 되돌립니다.

문서가 많을 때는 어떻게 하나요?

폴더 하나에 수백 개가 있으면 전부 처리하지 않습니다.

판정만 먼저 돌려 목록을 만들고, 글자층이 있는 것부터 처리합니다. 빠르고 정확합니다. 스캔 문서는 후보로만 표시하고 멈췄다가, 그중 정말 필요한 것만 골라 문자 인식을 돌립니다.

스캔 문서 수십 개에 문자 인식을 한 번에 거는 것을 피합니다. 시간이 오래 걸리고 중간에 끊기면 어디까지 했는지 알기 어렵습니다.

이렇게 채팅창에 붙여 넣으세요

ChatGPT나 Claude에서 새 대화를 열고, 아래 GitHub 주소와 요청문을 함께 붙여 넣으세요. 정리할 문서도 첨부하면 됩니다.

GitHub에는 AI가 읽을 스킬 지침과 참고자료, 판정에 쓰는 코드가 함께 들어 있습니다.

처음 사용할 때는 이렇게 요청하세요

https://github.com/jyedi1257-max/hwp-docs-to-markdown

이 GitHub의 한글 문서 추출 스킬을 적용해서
첨부한 문서에서 글을 뽑아줘.
SKILL.md와 필요한 참고자료를 읽고 그 기준을 따라줘.

먼저 파일 형식을 판정하고,
문서가 아닌 파일이 있으면 알려줘.

추출한 뒤에는 글자 수를 함께 적어줘.
결과가 짧으면 성공으로 보고하지 말고 왜 짧은지 알려줘.

폴더를 통째로 정리할 때

https://github.com/jyedi1257-max/hwp-docs-to-markdown

이 스킬로 [폴더 경로]를 정리하려고 해.

먼저 판정만 해서 목록을 보여줘.
형식별 개수와, 다시 받아야 할 파일을 구분해줘.
스캔 문서는 후보로만 표시하고 바로 문자 인식을 돌리지는 마.

목록을 보고 내가 처리할 것을 고를게.

컴퓨터에서 직접 돌릴 때

Claude Code나 Codex처럼 명령을 실행할 수 있는 환경이면 판정 스크립트를 그대로 쓸 수 있습니다.

https://github.com/jyedi1257-max/hwp-docs-to-markdown

이 스킬의 detect-format.py를 가져와서 [폴더 경로]에 돌려줘.
결과를 형식별로 정리해서 보여주고,
문서가 아닌 파일은 따로 묶어줘.

판정만 할 거라면 따로 설치할 것이 없습니다. PDF를 다루면 pymupdf, HWP를 다루면 pyhwp가 필요하고, 필요한 시점에 안내받으면 됩니다.

결과를 보고 다시 요청할 때

추출 결과가 짧게 나왔다면:

이 파일은 결과가 너무 짧아.
본문이 그림으로 들어간 건지, 파일 자체가 문제인지 구분해줘.
그림이라면 문자 인식으로 넘기는 방법을 알려줘.

한자가 섞여 나왔다면:

뽑은 글에 한자가 섞여 있어.
한 글자씩 바꾸지 말고 낱말 단위로 정리해줘.
정리한 뒤 남은 한자가 몇 자인지 다시 세어줘.

다른 자료에 잘 없는 것

공문서 서식의 표 안 체크박스는 보통 추출에서 조용히 사라집니다. 표는 보이는데 체크 여부가 빈칸으로 나와서, 정보가 없어진 줄도 모르고 넘어가기 쉽습니다.

체크 상태는 본문이 아니라 양식 개체에 들어 있습니다. 그 값을 읽어 표 셀과 순서대로 짝짓는 방법을 정리했고, 개수가 맞지 않으면 멈추라는 확인 절차도 함께 넣었습니다. 어긋난 채로 쓰면 엉뚱한 항목이 체크된 것으로 기록됩니다.

옛 HWP 3.0의 띄어쓰기도 그렇습니다. 이 형식은 요즘 도구가 대부분 열지 못해서, 변환한 뒤 한글 바이트만 골라 잇는 방법이 돌아다닙니다. 그렇게 뽑으면 낱말이 전부 붙어 나옵니다.

오늘은부모교육및상담에대하여살펴보겠습니다

이걸 변환 도구의 한계로 알고 띄어쓰기를 되살리려 애쓰기 쉽습니다. 그런데 원인은 변환이 아니라 추출 방법에 있습니다. 공백은 골라 내는 범위 밖이라 그대로 버려지는 것입니다. 글꼴 이름 같은 것이 본문에 섞여 들어오는 일도 같은 이유로 생깁니다.

변환 결과를 통째로 읽어 태그만 걷어내면 띄어쓰기가 그대로 남습니다. 어느 인코딩인지 몰라도 되도록, 깨진 글자를 되돌리는 처리까지 함께 넣었습니다. 없앤 정보는 되살아나지 않으니 애초에 지우지 않는 쪽이 맞습니다.

사용하면서 확인할 점

1. 판정 결과에서 문서가 아닌 파일을 먼저 걸렀는가?
2. 추출 결과의 글자 수를 확인했는가? 짧다면 이유를 알고 있는가?
3. 표가 있던 문서라면 표 안 내용이 살아 있는가?
4. 한자와 띄어쓰기를 정리했는가?
5. 다시 처리하지 않도록 어떻게 뽑았는지 기록했는가?