Preview 작업 공간에서 게시 전 검증하기

Preview 작업 공간은 Binder의 Markdown을 Web으로 공개하기 전에 구조와 렌더링을 검사하는 곳이다. 출판 워크벤치에서 Web 미리보기를 켜고 모두 빌드하면 이 화면으로 이동한다. 이 전환은 deploy 완료가 아니라 publish preparation handoff다.

화면의 세 영역

영역 확인할 것 여기서 하지 않는 것
왼쪽 구조 포함 문서, 순서, 선택 문서 원문 authority 변경
가운데 Preview 실제 렌더링, link, image, 반응형 결과 production URL 보장
오른쪽 Site 설정 제목, menu, access, SEO·analytics provider 상태를 추측해 성공 처리

Preview는 임시 staging 경로나 renderer transport를 사용자에게 요구하지 않는다. 사용자가 다루는 기준은 Binder, 구조, 보이는 결과와 게시 설정이다.

출판 워크벤치에서 열기

  1. 출판 워크벤치 실습을 연다.
  2. PDF, DOCX와 EPUB은 끄고 Web preview만 켠다.
  3. 변경을 저장한다.
  4. 모두 빌드를 누른다.
  5. 최근 실행이 미리보기에서 열림인지 확인한다.
  6. 왼쪽 구조와 가운데 Preview가 함께 열린 것을 확인한다.

Preview 전환 뒤 상단의 출판물 Web handoff receipt를 확인한다. 상태가 미리보기에서 열림이면 저장된 출판물 snapshot의 handoff가 정상 종료된 것이다. 실패·취소·건너뜀과 구분하고, artifact 경로나 production URL이 없는 것은 정상이다.

Web Preview handoff 뒤 미리보기에서 열림 receipt가 표시된 화면

Preview를 직접 열어도 같은 작업 공간을 사용할 수 있다. 출판 워크벤치에서 여는 경우에는 어떤 출판물 snapshot에서 왔는지 실행 기록으로 남는다는 차이가 있다.

구조 검증

실습 Binder에서 다음을 확인한다.

  1. 제품 이야기, 출판 워크플로, 검토 체크리스트 순서가 유지된다.
  2. README가 공개 구조에 섞이지 않는다.
  3. 문서를 선택하면 해당 페이지가 Preview에 표시된다.
  4. 구조의 문서 수가 출판물에 저장한 수와 맞다.

문서가 빠졌다면 Preview에서 임의로 결과만 고치지 말고 Output Structure와 출판물 정의로 돌아가 source를 바로잡는다.

Web handoff 뒤 열린 Preview 작업 공간

렌더링 검증

최소한 다음 화면 크기로 같은 페이지를 확인한다.

범위 권장 확인
넓은 desktop navigation, 본문 폭, 표, 큰 image
200% 확대에 가까운 좁은 폭 control 겹침, 가로 overflow, 긴 제목
mobile 폭 menu 전환, image 축소, 표와 code block

01_product-story.md에서는 흐름 SVG가 잘리지 않는지, 02_workflow.md에서는 표가 읽히는지, 03_release-notes.md에서는 task list가 의도한 모양인지 확인한다.

왼쪽 구조와 가운데 빌드 준비 상태를 함께 확인하는 Preview 화면

이번 캡처는 Preview 작업 공간이 열리고 구조가 전달된 준비 상태까지의 증거다. 가운데 실제 site 렌더링과 하위 route parity는 별도 materialization 실행에서 확인해야 하므로 이 이미지 하나로 완료 처리하지 않는다.

링크와 자산 검증

  • 내부 문서 링크가 같은 preview origin 안에서 열린다.
  • image·video가 404 없이 표시된다.
  • anchor link가 올바른 heading으로 이동한다.
  • 외부 link의 scheme과 공개 가능 여부가 맞다.
  • 절대 로컬 경로가 HTML이나 오류 메시지에 노출되지 않는다.

Preview가 보인다는 사실만으로 연결된 모든 자산이 완성됐다고 판단하지 않는다. 첫 페이지뿐 아니라 하위 route를 직접 이동한다.

Site 설정과 함께 확인하기

오른쪽 Site 설정을 열어 title, base URL, menu, search·TOC, access 정책과 analytics 상태를 확인한다. 설정의 상세 의미는 사이트 설정 전체 가이드를 따른다.

Analytics는 특정 provider 이름보다 켜짐·꺼짐, 필요한 식별자, 적용 결과를 중심으로 설명한다. provider가 바뀌어도 Preview와 가이드의 제품 개념은 유지된다.

Preview와 deploy의 차이

Preview에서 확인됨 아직 확인되지 않음
Binder가 local Web 결과로 materialize됨 인터넷에서 production URL이 열림
local route와 asset이 보임 DNS·TLS·CDN이 정상임
저장된 Site 설정을 읽음 provider가 설정을 실제 적용함
Web handoff 실행 기록이 남음 배포 receipt와 production revision이 일치함

따라서 Preview 성공 뒤에는 별도의 preflight, provider 연결, 배포 progress, 반환 URL과 새 브라우저 검증이 필요하다.

실패할 때

  • 구조가 비어 있음: Binder와 Output Structure를 다시 불러오고 현재 구성 사용을 누른다.
  • 문서가 누락됨: 출판물에 저장된 경로가 현재 Binder에 존재하는지 확인한다.
  • 이전 내용이 보임: source 저장 여부와 preview restart·refresh 상태를 확인한다.
  • hugo.toml을 찾지 못함: 현재 Binder의 Site 초기화·설정 저장을 먼저 완료한다.
  • link나 image가 깨짐: source 기준 상대 경로와 공개 결과의 route를 각각 확인한다.
  • 배포 버튼이 준비되지 않음: Preview 성공과 provider credential·production preflight를 별개로 해결한다.

완료 체크리스트

  • 출판물의 문서 수와 Preview 구조가 같다.
  • desktop·좁은 폭·mobile에서 핵심 페이지를 확인했다.
  • 내부 link, image와 하위 route를 직접 열었다.
  • Site 설정과 접근 범위를 다시 확인했다.
  • Preview를 production 배포 완료로 기록하지 않았다.