Binder Graph로 문서 관계 탐색하기

Binder Graph는 현재 Scope의 Markdown 문서를 노드, 문서 사이의 내부 링크를 연결로 보여 주는 파생 보기다. 별도의 그래프 데이터베이스에 관계를 다시 입력하는 기능이 아니다. 링크를 추가하거나 고치면 Graph가 바뀌고, Graph의 배치·필터·확대 상태를 바꿔도 Markdown 원문은 바뀌지 않는다.

이 장에서는 재현 가능한 작은 프로젝트로 다음 작업을 모두 수행한다.

1. Markdown link가 Graph 관계가 되는지 원문과 대조한다.
2. 전체 보기에서 Scope의 연결 성분과 고립 문서를 읽는다.
3. is:hub 쿼리로 연결이 많은 문서를 찾고 선택한다.
4. 로컬 보기로 선택 문서의 1단계 이웃만 좁혀 본다.
5. 기본적으로 숨긴 _index.md를 포함해 섹션 구조까지 확인한다.
6. is:orphan으로 아직 연결되지 않은 문서를 찾는다.
7. 표시 설정, 저장한 뷰, 진단과 타임랩스를 운영한다.

Graph, Link Map, Mindmap의 차이

세 보기는 비슷해 보이지만 서로 다른 질문에 답한다.

Binder Graph에서 가까이 놓인 두 노드가 반드시 의미상 비슷하다는 뜻은 아니다. 화면 배치는 연결을 탐색하기 위한 표현이며, 확정적인 분류나 중요도 점수가 아니다.

실습 프로젝트 준비

Graph Lab 예제 전체를 별도 폴더에 복사하고 그 폴더를 Scope로 연다. 원본 fixture를 직접 수정하지 않으면 이 장의 기준 숫자를 언제든 다시 재현할 수 있다.

기본 상태의 기대값은 다음과 같다.

여기서 degree는 들어오거나 나가는 직접 연결을 합친 수다. _index.md를 포함하면 섹션 home이 문서들을 묶기 때문에 노드와 연결 수뿐 아니라 고립·연결 성분 수까지 달라진다.

1. 관계의 원본을 먼저 확인한다

00_product-hub.md의 핵심 부분은 다음과 같다.

# 제품 허브

제품 서사는 [사용자 조사](research/10_user-research.md)에서 시작해
[가치 제안](research/20_value-proposition.md)과
[출시 체크리스트](release/10_launch-checklist.md)로 이어집니다.

실증 자산은 [미디어 계획](release/20_media-plan.md)에서 관리합니다.

이 네 link가 제품 허브에서 나가는 연결이 된다. README.md가 제품 허브를 가리키므로 들어오는 연결 한 개가 더해져 기본 degree는 5다.

Graph는 이 관계를 frontmatter에 다시 쓰지 않는다. Markdown과 Scope index에서 파생하므로 cache를 다시 만들어도 원문 link가 같으면 관계를 복원할 수 있다.

2. Binder Graph를 연다

1. Graph Lab 폴더를 Scope로 연다.
2. 00_product-hub.md를 열어 원문 link를 확인한다.
3. 상단 workspace shortcut에서 그래프를 선택한다.
4. 오른쪽 Graph 정보 panel이 나타나고 노드가 배치될 때까지 기다린다.
5. 진단에서 노드 9, 연결 8, 고립 1, 연결 성분 3인지 확인한다.

처음에는 전체 모드이며 _index.md는 숨겨져 있다. 문서 관계를 먼저 읽기 위한 기본값이다.

화면에서 읽을 요소

label이 겹칠 수 있는 배율에서는 모든 이름을 동시에 표시하지 않는다. 노드를 선택하거나 확대해 확인하고, 이름이 보이지 않는다는 이유로 문서가 누락됐다고 판단하지 않는다.

3. 노드를 선택하고 후속 작업을 한다

노드를 선택하면 오른쪽 탐색 영역에 문서 이름과 동작이 나타난다.

canvas 바탕을 drag하면 보이는 영역을 옮기고, wheel로 확대·축소한다. 노드를 drag하면 탐색 중 위치를 조절할 수 있다. 이 조작은 Markdown link를 만들거나 삭제하지 않는다.

4. 필터 쿼리로 필요한 문서만 찾는다

필터의 쿼리에 일반 텍스트 또는 필드:값을 입력한다. 공백으로 나눈 여러 조건은 모두 만족해야 한다.

예를 들어 tag:product path:00_는 product tag가 있고 경로에 00_가 들어간 노드만 남긴다. 조건에 맞는 문서가 없으면 빈 Graph가 보일 뿐 원문이나 index가 삭제되지는 않는다. 해제로 쿼리를 비운다.

허브 찾기

1. 쿼리에 is:hub를 입력한다.
2. 일치 항목으로를 선택한다.
3. 00_product-hub가 선택되고 오른쪽에 이름이 표시되는지 확인한다.

is:hub는 고정된 문서 역할이 아니다. 현재 보이는 Graph의 최대 degree를 기준으로 계산하므로 link를 추가하거나 필터 범위를 바꾸면 결과가 달라질 수 있다.

5. 로컬 보기로 가까운 연결에 집중한다

전체 Graph가 복잡할 때는 노드를 선택한 뒤 쿼리를 해제하고 로컬을 선택한다. 로컬 깊이는 선택 노드에서 몇 단계 떨어진 관계까지 포함할지 정한다.

로컬 보기는 문서를 Scope에서 제외하는 기능이 아니다. 같은 Graph의 표시 범위만 좁힌다. 다른 cluster와 고립 문서를 다시 보려면 전체로 돌아간다.

6. _index.md로 섹션 구조까지 확인한다

Desktop Binder Graph는 문서 중심 관계를 먼저 보여 주기 위해 _index.md를 기본적으로 숨긴다. Hugo section home과 navigation 구조를 함께 점검할 때 오른쪽 표시 → 인덱스 파일 포함을 켠다.

Graph Lab에서는 toggle 하나로 다음 변화가 실제 관측됐다.

• 노드가 9개에서 12개로 증가한다.
• 연결이 8개에서 17개로 증가한다.
• 세 연결 성분이 하나로 이어진다.
• 고립 문서가 1개에서 0개가 된다.
• 제품 허브의 degree가 5에서 6으로 증가한다.

90_orphan-note.md의 본문에는 link가 없지만 root _index.md가 그 문서를 가리키므로 index를 포함한 Graph에서는 더 이상 고립이 아니다. “고립”은 절대적인 문서 속성이 아니라 현재 포함 범위에서 계산한 관계 상태다.

7. 고립 문서와 연결 성분을 진단한다

인덱스 파일 포함을 다시 끄고 고립을 선택하면 쿼리가 is:orphan으로 바뀐다. Graph Lab에서는 90_orphan-note.md 한 개만 남는다.

고립 문서가 항상 오류인 것은 아니다. 초안, 개인 메모, 수집 직후 문서는 의도적으로 독립적일 수 있다. 다음 순서로 판단한다.

1. 문서를 열어 목적과 상태를 확인한다.
2. 기존 hub나 section에서 찾을 수 있어야 하는 문서인지 판단한다.
3. 관계가 필요하면 의미가 맞는 문장에서 명시적 Markdown link를 작성한다.
4. index 완료 뒤 is:orphan 결과와 연결 성분 수를 다시 확인한다.

Graph에서 선을 직접 그어 관계를 만드는 방식은 사용하지 않는다. 관계의 이유가 읽히도록 Markdown 문맥 안에 link를 둔다.

진단 숫자 읽기

필터가 켜진 상태의 “보임” 수와 Scope 전체 수를 혼동하지 않는다. 쿼리를 해제하고 index 포함 상태를 확인한 뒤 기준 수를 기록한다.

8. 표시와 타임랩스를 조절한다

오른쪽 표시 영역은 원문이 아니라 현재 Graph 표현을 바꾼다.

• 노드 크기: 문서 원의 표시 배율
• 링크 두께: 연결선의 표시 배율
• 화살표: 방향 표시의 크기와 on/off
• 그룹 색상: group별 색 구분
• 인덱스 파일 포함: _index.md 노드와 구조 연결 포함 여부

상단 전체 맞춤은 현재 보이는 노드 묶음을 canvas 안에 다시 배치한다. 너무 멀리 이동하거나 확대해 Graph를 잃었을 때 먼저 사용한다. 그래프 컨트롤 초기화는 표시·필터·모드 값을 기본값으로 되돌린다.

타임랩스

Graph를 다시 재생하면 같은 파생 관계 위에서 노드가 나타나고 배치가 정착하는 과정을 볼 수 있다. 애니메이션 속도를 조절하고 재생 중에는 일시정지·계속·정지를 사용할 수 있다. 타임랩스는 새 관계를 만들지 않는다.

운영체제에서 동작 감소를 켠 환경에서는 긴 타임랩스 대신 seed layout을 새로고침한다. 중요한 상태나 진단을 애니메이션만으로 전달하지 않는다.

9. 반복 작업은 저장한 뷰로 남긴다

필터, 전체·로컬 모드, 로컬 깊이, index 포함과 표시 배율을 조정한 뒤 뷰 이름을 입력하고 뷰 저장을 선택한다. 예를 들면 다음처럼 목적을 이름에 포함한다.

• 고립 문서 검토
• research 허브
• section index 포함

저장한 뷰를 적용하면 그때 저장한 탐색·표시 조건으로 돌아간다. 저장한 뷰는 Markdown 문서나 publish 결과가 아니라 앱의 Graph 작업 상태다. 팀과 공유해야 하는 분류 기준은 저장 뷰 이름만으로 전달하지 말고 문서의 link, tag와 section 구조에 반영한다.

전체 조작 영상

다음 10.9초 영상은 제품 허브 원문에서 시작해 전체 Graph를 열고, is:hub 필터와 일치 항목 선택, 로컬 보기, _index.md 포함, is:orphan 진단까지 실제 Glif에서 이어서 수행한다.

예상과 다를 때

원본 보존과 검증 범위

이 장이 검증하는 canonical 기능 ID는 VW-01이다. 캡처는 Glif 0.1.0, Windows, 한국어, dark theme, 1200×800 앱 client area에서 수행했다. 캡처 전후 Graph Lab의 12개 Markdown 파일을 SHA-256으로 비교해 같은 값인지 확인했다.

• 확인함: Markdown-link-derived graph, 전체 보기, 허브 쿼리, 일치 항목 선택, 로컬 보기, _index.md 포함, 고립 쿼리, 원문 보존
• 자동 기능 검증: Binder Graph TypeScript suite 106개 통과
• native index 회귀 검증: section _index.md 보존 관련 Rust 표적 테스트 2개 통과
• 아직 주장하지 않음: 공개 Hugo graph 화면 동등성, 노드 drag 위치의 세션 간 지속성, screen reader 사람 청취, 외부 mount 폴더의 Graph 동등성

완료 확인

• Graph, Link Map과 Mindmap이 각각 어떤 원본과 범위를 쓰는지 설명할 수 있다.
• 기본 상태에서 노드 9, 연결 8, 고립 1, 연결 성분 3을 확인했다.
• 제품 허브의 네 outgoing link와 한 incoming link를 원문에서 찾았다.
• is:hub으로 제품 허브를 선택하고 로컬 깊이 1 이웃을 확인했다.
• _index.md 포함 뒤 노드 12, 연결 17, 고립 0, 연결 성분 1을 확인했다.
• is:orphan 결과가 index 포함 상태에 따라 달라지는 이유를 설명할 수 있다.
• 표시 설정과 저장한 뷰가 Markdown 원본이 아닌 파생 작업 상태임을 이해했다.
• Graph에서 관계를 직접 그리지 않고 의미가 드러나는 Markdown link로 수정했다.

다음에는 보기와 Projection 선택에서 Graph를 다른 구조화 보기와 비교하거나, 링크 상태와 로컬 그래프 읽기에서 현재 문서의 backlink·forward·broken link를 원문 위치별로 점검한다.