Blueprint로 문서 구조 점검하기

Blueprint는 현재 Markdown 문서의 heading, 문서 참조, 외부 링크, 이미지와 임베딩을 원문 순서대로 펼쳐 보여 주는 구조 보기다. 문서를 다른 형식으로 변환하거나 별도 설계도 데이터를 만드는 기능이 아니다. 노드를 선택하면 언제든 원문의 해당 줄로 돌아가며, 표시 설정만 문서별 projection profile에 저장된다.

이 장에서는 Blueprint 실증 작업실을 사용한다. 예제 Binder에는 정상 구조뿐 아니라 끊긴 링크, 구조가 없는 산문, 빈 문서까지 들어 있어 성공 경로와 fallback을 함께 확인할 수 있다.

무엇을 확인할 수 있나

Blueprint 요소 Markdown의 근거 선택했을 때
문서 노드 현재 활성 Markdown 문서 원문 첫 줄을 연다
heading 노드 코드 펜스 밖의 #~###### ATX heading heading이 시작되는 줄로 이동한다
참조 노드 Markdown 링크와 wiki link 참조가 적힌 원문 위치로 이동한다
에셋 노드 Markdown 이미지와 wiki embed 에셋 참조가 적힌 원문 위치로 이동한다
연결 상태 Binder LinkMap과 문서 내부·외부 URL 판정 연결됨, 끊긴 링크, 외부, 문서 내부, 확인 중을 구분한다

같은 문서 안에서 반복된 참조도 하나로 합치지 않는다. 각 occurrence가 서로 다른 원문 위치이므로 별도 노드로 남는다. 반대로 fenced code block 안의 heading과 링크 예시는 실제 문서 구조가 아니므로 Blueprint에서 제외된다.

예제 Binder 열기

  1. 예제 폴더 blueprint-lab을 로컬로 준비한다.
  2. Glif에서 이 폴더를 Binder로 등록하고 전환한다.
  3. 01_blueprint-tour.md를 연다.
  4. 원문에서 heading, wiki link, 외부 링크, Resources/ 이미지, 존재하지 않는 Markdown 링크가 모두 보이는지 확인한다.

Blueprint가 읽는 Markdown 원문

예제의 Resources/blueprint-cycle.svg와 Resources/blueprint-detail.svg는 Glif의 Binder 리소스 경로 계약을 따른다. 이미지 파일을 Binder 밖의 임의 경로에 두지 않는다.

Blueprint 열기

다음 두 진입점 중 하나를 사용한다.

  • 상단 Workspace 메뉴에서 Blueprint를 선택한다.
  • Ctrl+P로 명령 검색을 열고 Blueprint를 실행한다.

Blueprint는 독립 content panel로 열린다. 문서 header의 Source·Page·Slide 같은 보기 형식을 바꾸는 항목이 아니며, 현재 활성 Markdown 문서를 따라간다. 다른 문서를 편집기에서 열면 Blueprint도 그 문서의 구조를 다시 읽는다.

처음 열면 기본값은 가로, 여유롭게, 참조 표시 켬, 에셋 표시 켬이다.

기본 가로 방향의 Blueprint

상단 요약에는 이 예제에서 파생된 헤딩 6, 참조 5, 에셋 2, 끊긴 링크 1, 확인 중 2가 표시된다. 확인 중 2는 문서 LinkMap이 직접 추적하지 않는 두 로컬 에셋이며, 존재를 성공으로 추정하지 않는 상태다. 숫자는 현재 원문과 표시 필터를 혼동하지 않도록 전체 모델 기준으로 유지된다.

방향 전환하기

방향에서 다음 중 하나를 선택한다.

  • 가로: 같은 깊이의 구조를 좌우 흐름으로 비교한다. 넓은 창에서 큰 계층을 훑을 때 적합하다.
  • 세로: 원문 순서를 위에서 아래로 따라간다. 좁은 panel이나 긴 문서에서 적합하다.

가로 구조가 panel 폭보다 크면 아래 가로 스크롤을 사용한다. 세로 구조에서도 깊은 자식은 들여쓰기되므로 가로 스크롤이 나타날 수 있다. 방향 전환은 원문이나 링크 관계를 바꾸지 않는다.

밀도 조절하기

밀도에서 다음 중 하나를 선택한다.

  • 여유롭게: 노드의 label, target, 상위 heading, 상태를 넉넉한 간격으로 읽는다.
  • 촘촘하게: 같은 화면에 더 많은 노드를 배치해 큰 문서를 빠르게 훑는다.

세로와 촘촘하게를 함께 사용하면 source order와 계층 들여쓰기를 유지하면서 긴 구조를 비교하기 쉽다.

세로·촘촘하게 설정한 Blueprint

참조와 에셋 좁혀 보기

표시 스위치는 구조를 삭제하지 않고 현재 panel에서만 필터링한다.

  • 참조 표시를 끄면 문서 링크와 외부 링크 노드를 숨긴다.
  • 에셋 표시를 끄면 Markdown 이미지와 wiki embed 노드를 숨긴다.
  • 두 스위치를 다시 켜면 원래 source order 위치에 노드가 돌아온다.

heading 계층은 항상 남는다. 참조와 에셋을 숨겨도 원문의 실제 내용이나 Binder LinkMap은 바뀌지 않는다.

링크 상태 읽기

참조와 에셋 노드 오른쪽 상태를 다음처럼 해석한다.

상태 의미 다음 행동
연결됨 Binder 안에서 목적지를 찾았다 선택해 원문 occurrence를 확인한다
끊긴 링크 LinkMap 인덱싱이 끝났지만 목적지가 없다 원문 target을 고치거나 목적지 문서를 만든다
외부 https:, mailto: 같은 외부 scheme이다 URL이 의도한 주소인지 원문에서 검토한다
문서 내부 #section처럼 현재 문서 안을 가리킨다 fragment와 실제 heading을 함께 점검한다
확인 중 LinkMap이 없거나 아직 완전하지 않다 인덱싱이 끝날 때까지 기다린 뒤 다시 확인한다

예제의 99_missing-destination.md는 의도적으로 존재하지 않는다. 따라서 아직 없는 목적지 노드와 상단 끊긴 링크 1이 함께 보여야 한다.

목적지가 없는 참조를 숨기지 않고 표시한 상태

확인 중은 연결됨과 같은 뜻이 아니다. 인덱싱 결과가 없을 때 Blueprint는 성공으로 추정하지 않고 불확실성을 그대로 표시한다.

원문의 정확한 위치로 돌아가기

  1. 마우스로 Blueprint 노드를 선택하거나 Tab으로 노드에 포커스를 옮긴다.
  2. Enter 또는 Space를 누른다.
  3. Glif가 현재 문서를 Source editor로 열고 노드가 파생된 line과 column으로 이동한다.

키보드 포커스가 표시된 Blueprint 노드

문서 노드는 첫 줄, heading은 # 위치, 참조와 에셋은 해당 Markdown 문법이 시작되는 위치를 가리킨다. Blueprint에서 원문을 직접 수정하지는 않는다. 수정은 Source editor에서 하고, 저장된 원문을 Blueprint가 다시 파생한다.

전체 상호작용 보기

아래 영상은 같은 release candidate에서 가로→세로 전환, 밀도 변경, 참조 숨김·복원, 끊긴 링크 키보드 포커스, 원문 이동, Blueprint 재열기까지 연속으로 기록했다. 파란 포인터는 실제 클릭 위치이며 하단 caption은 각 검증 행동을 설명한다.

문서별 설정 저장과 복원

방향, 밀도, 참조 표시, 에셋 표시는 현재 문서의 projection profile에 자동 저장된다. 저장 상태는 control 오른쪽에서 확인한다.

  • 기본 설정: 아직 profile이 없어 기본값으로 보고 있다.
  • 설정 저장 중: 변경값을 안전하게 기록하고 있다.
  • 문서 설정 저장됨: 현재 문서와 설정이 기록됐다.
  • 설정 확인 필요: profile을 읽거나 쓰지 못해 점검이 필요하다.

Blueprint를 닫았다 다시 열거나 다른 문서로 갔다 돌아와도 같은 문서의 설정이 복원된다.

재열기 뒤 세로·촘촘하게 설정이 복원된 상태

설정은 .glif/profiles/v1/ 아래 관리 파일에 들어간다. 이 JSON을 직접 편집하지 않는다. profile은 표시 의도만 저장하며 Markdown 원문을 대신하지 않는다. 현재 Blueprint 설정은 Desktop 전용이고 Hugo·Slide publish 결과로 전송되지 않는다.

구조가 없는 문서

지원하는 heading, 링크, 이미지가 하나도 없는 산문 문서도 빈 화면으로 만들지 않는다. Blueprint는 줄 번호가 붙은 제한된 원문 excerpt를 제공한다. 각 줄을 선택하면 Source editor의 그 줄로 돌아간다.

heading과 참조가 없는 산문 문서의 줄 단위 fallback

이 fallback은 전체 문서를 복제한 별도 편집기가 아니다. 구조를 만들고 싶다면 원문에 ATX heading이나 참조를 추가한다.

빈 문서

공백만 있는 Markdown에서는 빈 문서 상태와 원문 열기 행동을 제공한다. 데이터를 만든 것처럼 가짜 노드를 표시하지 않는다.

빈 Markdown 문서의 Blueprint 상태

원문에 heading, 링크 또는 이미지를 추가하고 저장하면 Blueprint가 구조 보기로 전환된다.

문제 해결

Blueprint가 활성 문서 없음을 표시한다

Markdown 문서를 Source editor에서 먼저 연다. PDF나 이미지 자체를 활성화한 상태에서는 Markdown 구조를 파생할 수 없다.

모든 내부 링크가 확인 중이다

Binder 전환 직후라면 LinkMap 인덱싱이 끝나지 않았을 수 있다. 잠시 기다린 뒤 문서를 다시 열거나 Binder를 새로고침한다. 확인 중인 노드를 연결됨으로 간주해 출판하지 않는다.

이미지가 Blueprint에는 있지만 Source preview에서 보이지 않는다

에셋이 Binder의 Resources/ 아래에 있는지 확인하고 Markdown target도 Resources/file-name.ext 형식으로 맞춘다. 파일 이름의 대소문자와 확장자도 확인한다.

설정 저장됨이 나타나지 않는다

Binder와 문서가 쓰기 가능한지 확인한다. .glif 폴더를 삭제하거나 profile JSON을 손으로 고치지 말고, 오류 메시지를 보존한 채 다시 시도한다.

노드를 눌러도 원하는 위치가 아니다

같은 링크가 여러 번 쓰였다면 각 occurrence는 별도 노드다. label뿐 아니라 노드의 원문 행 번호를 확인한다.

기능 경계

Blueprint가 하는 일과 하지 않는 일을 구분한다.

지원 지원하지 않음
Markdown 구조를 원문 순서로 파생 노드를 자유 배치하는 diagram editor
heading 계층과 참조·에셋 표시 connector를 직접 만들거나 수정
LinkMap 기반 상태 진단 Blueprint에서 Markdown 본문 편집
원문 line·column으로 이동 profile을 Hugo 출력에 자동 포함
문서별 표시 설정 저장·복원 Canvas, Graph, Mindmap을 대체
산문·빈 문서 fallback PDF·이미지 파일 자체의 구조 분석

자유 배치와 조립은 Cart와 Assembly Canvas, 문서 간 전체 연결 탐색은 Graph, heading 중심 탐색은 Outline·Mindmap, 관계 표의 시각화는 Diagram을 사용한다.

실증 점검표

  • 01_blueprint-tour.md 원문과 Blueprint가 같은 heading 6개를 가리킨다.
  • 참조 5개와 에셋 2개가 source order로 보인다.
  • 99_missing-destination.md가 끊긴 링크 1개로 표시된다.
  • 가로·세로와 여유롭게·촘촘하게를 각각 전환했다.
  • 참조와 에셋 표시를 끄고 다시 켰다.
  • 키보드로 노드에 포커스하고 원문의 정확한 줄로 이동했다.
  • Blueprint를 다시 열어 문서별 설정이 복원됐다.
  • 산문과 빈 문서 fallback을 확인했다.
  • Blueprint 조작 전후 Markdown과 Resources/ 파일이 바뀌지 않았다.

이 가이드의 자동 실증에서는 위 항목과 함께 source SHA-256 동일성, projection profile의 vertical·compact 복원, 콘솔 오류 0건을 확인했다. 세부 결과는 blueprint-evidence.json에서 확인할 수 있다.

검증 기능 ID는 VW-35이며, 캡처와 가이드 검증 기준일은 2026-08-02다.