Source 형식별 지원과 문제 해결
Source Preview와 GLIF로 가져오기는 형식마다 지원 범위가 다르다. preview 가능은 읽기 전용 내용을 만들 수 있다는 뜻이고, import 가능은 별도의 Markdown artifact를 생성할 수 있다는 뜻이다.
지원 상태 요약
| family | 형식 | preview | GLIF로 가져오기 | 대표 결과·주의 |
|---|---|---|---|---|
| 한글 | HWP | 지원 | 지원 | sibling Markdown, 실제 문서 corpus에서 fidelity 확인 필요 |
| 한글 | HWPX | 지원 | 지원 | sibling Markdown과 resource, 구조 변환 결과 확인 |
| 문서 | DOCX | 지원 | 지원 | sibling Markdown과 추출 media, 조판 동일성은 미보장 |
| 문서 | HTML / HTM | 지원 | 지원 | 단일 파일은 sibling Markdown, docset은 별도 folder 흐름 |
| 문서 | ODT | 지원 | 지원 | 표·링크·이미지·각주 지원, code identity 제한 |
| 문서 | RTF | 지원 | 지원 | 문단·링크 중심, 표·이미지·중첩 list 깊이는 제한 |
| 문서 | EPUB | 지원 | 지원 | spine 순서 기반 Markdown, 큰 책은 제한과 진단 확인 |
| slide | PPTX | 지원 | 미지원 | slide text preview-only |
| 지원 | 테스트 | layout·table·scan/OCR fidelity risk를 반드시 확인 | ||
| sheet | XLSX | 지원 | 지원 | single-sheet .md, multi-sheet folder |
| sheet | XLS | 지원 | 미지원 | legacy workbook preview-only |
| sheet | CSV | 지원 | 지원 | sibling Markdown table |
| sheet | TSV | 지원 | 지원 | sibling Markdown table |
| sheet | ODS | 지원 | 지원 | single/multi-sheet 규칙, 병합 셀 flatten |
Capability badge 해석
| badge | 의미 | 권장 행동 |
|---|---|---|
| 미리보기 준비됨 | 읽기용 projection 생성 성공 | 내용과 구조를 확인 |
| 미리보기 확인 중 | capability/변환 확인 중 | 완료될 때까지 기다림 |
| 미리보기 제한됨 | 내용을 만들지 못했거나 일부만 가능 | 이유 확인 후 원본 열기 |
| 가져오기 준비됨 | 현재 Binder와 위치에서 Markdown 생성 가능 | preview 검토 후 실행 |
| 가져오기 확인 중 | 형식 또는 쓰기 권한 preflight 중 | 결과가 바뀔 때까지 기다림 |
| 가져오기 불가 | preview-only, 권한 또는 runtime 제한 | 표시된 이유를 해결하거나 원본 유지 |
결과 경로 규칙
단일 문서와 표
대부분의 단일 source는 같은 폴더에 sibling Markdown을 만든다.
brief.docx → brief.md
data.csv → data.md
book.epub → book.md이미지가 추출되는 형식은 결과 Markdown 옆의 Glif 관리 resource 경로를 함께 사용할 수 있다. 이 파일을 임의로 분리하면 이미지 참조가 끊길 수 있다.
여러 sheet workbook
report.xlsx
report/
├── _index.md
├── Summary.md
└── Milestones.mdsheet 이름은 안전한 파일명으로 정규화된다. 병합 셀 span은 Markdown에 그대로 존재하지 않으므로 flatten 경고를 읽는다.
HTML 문서셋
index.html 또는 index.htm이 있는 폴더는 개별 파일 Source Preview와 다르게 Binder로 가져오기를 사용한다.
api-docs/ 원본 HTML 폴더
api-docs-markdown/ 변환된 sibling Markdown 문서셋local link와 asset을 상대 구조에 맞춰 변환하고, 깨진 local link가 있으면 완료 summary에서 경고한다. remote JavaScript를 실행하는 browser mirroring 기능이 아니다.
가져오기가 비활성인 이유
| 이유 | 의미 | 조치 |
|---|---|---|
| active project 필요 | 가져올 결과의 소유 Binder가 없음 | 대상 Binder를 먼저 연다 |
| 쓰기 권한 확인 중 | output 위치를 아직 검사 중 | 잠시 기다린다 |
| 쓰기 불가 | read-only 또는 연결 불가 mount | writable Binder 위치로 이동하거나 연결 복구 |
| capability unavailable | 변환 runtime 또는 파일 구조를 사용할 수 없음 | 형식·파일 손상·앱 package 상태 확인 |
| unsupported | preview-only 또는 미지원 형식 | 원본 열기나 다른 변환 경로 사용 |
Source Preview header, Shelf context menu와 import 알림은 같은 block reason 계약을 사용한다. 표면마다 서로 다른 이유가 보이면 회귀로 보고 기록한다.
변환 손실을 검토하는 법
문서 계열
- heading과 문단 순서
- 표의 행·열과 병합 표현
- 링크 목적지와 footnote
- image 파일과 alt text
- code block, nested list와 특수 객체
spreadsheet 계열
- sheet 수와 순서
- 날짜·시간·백분율·통화 표시
- formula의 표시값과 원식 보존 여부
- merged cell flatten 경고
- 빈 행·열과 delimiter 처리
PDF 테스트 import
- text-first PDF의 읽기 순서
- 표가 문단으로 무너지는지
- header/footer 반복
- image-heavy 페이지와 scan/OCR 경계
- page layout이 Markdown에서 재현되지 않는다는 점
PDF의 테스트 표시는 안정 import와 같은 품질 보증이 아니라 명시적 평가 경로라는 뜻이다.
문제 해결
| 증상 | 확인 | 복구 |
|---|---|---|
| source가 Shelf에 보이지 않음 | 지원 확장자, hidden/ignore 규칙, 현재 Binder | Binder를 다시 열고 목록 새로고침. 계속 누락되면 회귀로 기록 |
| click해도 editor가 열리지 않음 | source는 editor가 아니라 Source Preview가 기본 | Source Preview tab과 오류 안내 확인 |
| preview가 비어 있음 | 파일 손상, 암호화, 지원하지 않는 내부 구조 | 원본 열기로 확인하고 다른 파일로 재저장 후 재시도 |
| 가져오기 버튼이 비활성 | capability badge와 block reason | Binder·쓰기 권한·형식 지원 상태를 해결 |
| 결과 Markdown이 열리지 않음 | 결과 파일 생성 여부와 editor 오류 | Shelf를 새로고침하고 결과 경로에서 직접 연다 |
| 표 구조가 달라짐 | merged cell·고급 number format·layout | 원본과 비교해 Markdown에서 명시적으로 보정 |
| 다시 가져오기가 충돌 | 기존 sibling 결과 존재 | 기존 결과를 검토·이름 변경한 뒤 의도적으로 재실행 |
실패 시 지켜지는 것
- 원본 source를 삭제하거나 덮어쓰지 않는다.
- 기존 성공 산출물을 조용히 불완전 결과로 교체하지 않는다.
- unsupported element와 fidelity 경고를 성공처럼 숨기지 않는다.
- 별도 converter나 plugin을 조용히 내려받아 fallback하지 않는다.
- 임시 경로와 내부 실행 파일 위치를 공개 가이드에 노출하지 않는다.
실습 절차와 실제 캡처는 Source Preview와 GLIF로 가져오기에서 확인한다.