첫 시작 문제 해결

증상	먼저 확인할 것	복구 방법	보존되는 것
잘못된 폴더를 열었다	현재 Scope 경로	올바른 fixture 폴더를 다시 연다	기존 폴더의 원본 파일
Shelf에 문서가 없다	.md 파일 존재와 현재 Scope	디스크의 fixture를 확인하고 다시 연다	디스크에 남은 Markdown
찾는 문서가 범위 밖이다	현재 작업 범위	범위를 해제하거나 상위 범위로 바꾼다	Scope 전체 파일
미리보기 대상이 다르다	현재 Binder	fixture Binder를 선택하거나 만든다	원본 문서
브라우저가 열리지 않는다	preview 준비 상태와 현재 주소	preview를 다시 준비한 뒤 브라우저에서 열기를 다시 선택한다	생성 전 원본과 Binder 설정
사이트는 열리지만 페이지가 빠졌다	Binder에 포함된 문서와 build 오류	빠진 문서를 포함하고 오류를 해결한 뒤 다시 미리본다	성공 전 원본

성공으로 오인하지 않기

• 앱 안에 문서가 보이는 것만으로 Hugo build가 성공한 것은 아니다.
• 로컬 사이트가 열리는 것만으로 인터넷 공개가 완료된 것은 아니다.
• 현재 작업 범위를 좁힌 것은 파일을 다른 폴더로 이동한 것이 아니다.

다음

같은 Markdown을 Kanban으로 활용하기

재현 순서

문제가 다시 생기면 앱 화면만 설명하지 말고 다음 다섯 값을 함께 기록한다.

1. Glif 버전, Windows 배율, 언어와 테마
2. 현재 Scope의 절대 경로 대신 프로젝트 이름과 Binder 상대 경로
3. 실패한 Markdown 파일의 SHA-256과 마지막으로 성공한 시각
4. Shelf·Binder·Preview에서 선택한 항목
5. 상태 문구, build log의 오류, 브라우저 주소와 HTTP 상태

비밀키·토큰·개인 경로는 캡처와 log에서 지운다. 동일한 fixture를 새 임시 폴더에 복사해 .glif를 제외하고 다시 열면 원본 문제와 저장된 profile 문제를 분리할 수 있다.

Scope와 Binder를 분리해 확인하기

• Scope가 열리지 않음: 폴더가 실제로 존재하고 읽기 권한이 있는지 확인한다. 네트워크 드라이브나 이동식 디스크는 먼저 로컬 복사본으로 재현한다.
• Shelf는 보이지만 Binder가 비어 있음: Binder 포함 규칙과 상대 경로를 확인한다. 파일을 다시 만들기 전에 Finder/Explorer에서 실제 파일이 있는지 확인한다.
• 다른 파일이 preview됨: Preview 진입 전에 현재 Binder와 문서 경로를 다시 선택한다. 브라우저 탭을 새로 고쳐도 Binder 선택은 자동으로 바뀌지 않는다.
• 재실행 후 selection이 사라짐: 선택·scroll·검색은 session 상태일 수 있다. .glif/projections.json에 저장되는 기본 보기와 혼동하지 않는다.

Preview 실패와 안전한 재시도

1. 실행 중인 로컬 preview를 닫고 현재 Binder의 build log를 저장한다.
2. 수정 중인 Markdown을 저장한 뒤 preview 대상을 다시 선택한다.
3. 문서 수가 많으면 최소 fixture 한 개만 포함한 새 Binder에서 먼저 build한다.
4. 같은 오류가 재현되면 Source → 로컬 preview → 브라우저 결과 순서로 세 화면을 캡처한다.
5. 오류가 사라졌다면 원래 Binder에 파일을 하나씩 다시 포함해 문제 파일을 좁힌다.

public 폴더를 수동으로 고치면 다음 build에서 덮어써질 수 있다. 결과가 틀리면 생성물을 편집하지 말고 원본 Markdown, Binder 구성 또는 설정에서 수정한다.

확인 완료 기준

• 올바른 Scope와 Binder가 선택되어 있다.
• fixture의 Markdown과 asset 파일이 실제로 존재한다.
• Source 저장 후 SHA-256이 예상한 값이다.
• Preview log에 실패가 없고 브라우저 주소가 현재 build를 가리킨다.
• 새 브라우저에서 제목·본문·asset이 모두 로드된다.
• 같은 절차를 임시 fixture에서 한 번 재현했다.

문제 해결의 목표는 오류 문구를 숨기는 것이 아니라, 원본·선택 범위·생성 결과 중 어느 경계에서 어긋났는지 확인하고 복구 가능한 상태로 돌아가는 것이다.

오류 화면과 원본을 함께 보존

문제 해결은 상태 문구를 지우는 작업이 아니다. 아래 캡처와 원본을 한 세트로 남긴다.

• 오류가 난 화면의 상태 문구와 현재 Binder를 기록한다.
• 관련 Markdown의 저장 전후 diff와 파일 hash를 보존한다.
• preview log에서 실패한 파일과 결과 경로를 확인한다.
• 임시 fixture에서 같은 오류가 재현되는지 확인한 뒤 원래 Scope를 복구한다.