링크 상태와 로컬 그래프 읽기

Link Map은 현재 문서의 연결 상태를 한 작업면에 모은다. 백링크는 다른 문서에서 현재 문서로 들어오는 관계, 포워드 링크는 현재 문서에서 다른 문서로 나가는 관계, 깨진 링크는 현재 Scope에서 대상 문서를 찾지 못한 Markdown link다. 위쪽 로컬 그래프는 이 세 숫자 중 해결된 직접 연결을 방향과 함께 보여 준다.

이 장에서는 다음 상태를 실제 Glif에서 만든다.

관측값 기대 결과 근거 문서
백링크 2 incident-note.md, release-runbook.md
포워드 링크 1 metadata-contract.md
깨진 링크 1 missing-recovery-plan.md
로컬 그래프 node 4 현재 문서 1 + 해결된 직접 연결 3

실습 파일은 다섯 개다.

1. 세 방향을 먼저 구분한다

링크 수를 하나의 “연결 수”로 합치면 문제를 찾기 어렵다. 같은 두 문서 사이에도 누가 누구를 가리키는지에 따라 다음 행동이 달라진다.

종류 방향 질문 일반적인 다음 행동
백링크 다른 문서 → 현재 문서 어디에서 이 문서를 참조하는가? 원문 문맥을 열어 label과 의도를 확인
포워드 링크 현재 문서 → 다른 문서 현재 문서가 어디로 나가는가? 현재 문서의 link 위치와 target을 확인
깨진 링크 현재 문서 → 찾지 못한 대상 어떤 target이 현재 Scope에 없는가? 항목을 눌러 원문 위치에서 path 수정

백링크와 포워드 링크는 의미의 좋고 나쁨을 평가하는 점수가 아니다. 현재 Binder index가 읽은 Markdown 관계의 방향별 개수다. 인덱스 재구성 중에는 이전 snapshot 또는 불완전한 값을 볼 수 있으므로 최종 점검은 인덱스 완료 뒤에 한다.

ℹ️
외부 URL, mailto:, tel:, 현재 문서 안의 #fragment와 image target은 로컬 문서 존재 여부로 판정하는 깨진 문서 link 목록과 목적이 다르다. 외부 연결 검사는 publish preflight나 별도 URL 검사 흐름에서 수행한다.

2. 재현 가능한 관계를 준비한다

focus.md의 핵심 원문은 다음과 같다.

## 연결된 자료

- [메타데이터 계약](metadata-contract.md)
- [복구 계획](missing-recovery-plan.md)

첫 target은 같은 폴더에 실제 파일이 있으므로 포워드 링크가 된다. 두 번째 target은 의도적으로 존재하지 않으므로 깨진 링크가 된다.

두 backlink 원문은 각각 다음처럼 현재 문서를 가리킨다.

릴리즈 전 [운영 지식 허브](focus.md)의 링크 상태를 확인한다.
복구 뒤 [운영 지식 허브](focus.md)에 검증 결과를 반영한다.

파일 수만 맞추는 것으로는 충분하지 않다. focus.md를 현재 문서로 열고 두 incoming link의 target이 정확히 focus.md인지 확인한다.

3. Link Map을 연다

  1. link-health 폴더를 Scope로 연다.
  2. launcher에서 focus.md를 연다.
  3. Ctrl+P를 누르고 링크 맵을 검색한다.
  4. panel 결과를 선택한다.
  5. 오른쪽 요약에서 인덱스 완료를 기다린다.

상단 정보 도구의 link 아이콘으로도 같은 panel을 열 수 있다. Link Map은 현재 활성 문서를 기준으로 바뀌므로, 숫자를 기록하기 전에 editor header가 focus인지 확인한다.

운영 지식 허브의 로컬 그래프와 백링크 2, 포워드 링크 1, 깨진 링크 1, 인덱스 완료 badge

이번 실증에서는 다음을 동시에 확인했다.

  • 현재 node focus가 강조된다.
  • 들어오는 node는 incident-note, release-runbook 두 개다.
  • 나가는 해결된 node는 metadata-contract 한 개다.
  • missing-recovery-plan.md는 해결된 graph node가 아니라 깨진 링크 목록에 남는다.
  • badge는 백링크 2, 포워드 링크 1, 깨진 링크 1, 인덱스 완료다.

4. 로컬 그래프를 읽는다

로컬 그래프는 전체 Scope의 모든 문서를 한꺼번에 펼치는 그래프가 아니다. 현재 문서와 직접 연결된 문서를 빠르게 읽는 요약이다.

화면 요소 의미
강조된 중심 node 현재 활성 문서
중심으로 들어오는 연결 backlink 방향
중심에서 나가는 화살표 forward 방향
graph에 없는 깨진 target 대상 문서를 찾지 못해 해결된 node로 만들 수 없음

node에 pointer를 올리면 강조가 바뀌고, 다른 node를 선택하면 해당 문서를 연다. graph 바탕을 drag하면 위치를 옮길 수 있고 wheel로 확대·축소할 수 있다. 이 조작은 Markdown 원문이나 link 방향을 바꾸지 않는다.

Link Map, Binder Graph와 Mindmap의 차이

보기 중심 적합한 질문
Link Map 현재 문서와 직접 관계 이 문서로 들어오고 나가는 link는 무엇인가?
Binder Graph Scope 전체 관계 문서 집합 전체에서 hub와 cluster는 어디인가?
Mindmap 현재 Markdown heading tree 이 문서 내부의 section 구조는 어떻게 생겼는가?

Link Map의 node 수를 Scope 전체 문서 수로 해석하지 않는다. 현재 예제에 파일은 다섯 개지만 해결된 직접 관계만 그리므로 node는 네 개다.

5. 관계 목록에서 원문 문맥을 확인한다

그래프가 방향을 빠르게 보여 준다면 아래 목록은 실제 수정 지점을 제공한다.

  • 백링크: incident-note, release-runbook의 원문 line과 문맥
  • 포워드 링크: 현재 focus.md 안의 metadata-contract.md 위치
  • 깨진 링크: 현재 focus.md 안의 missing-recovery-plan.md 위치

백링크 두 곳과 포워드 링크 한 곳을 방향별 목록으로 표시한 Link Map

같은 문서가 여러 line에서 현재 문서를 가리키면 관계 문서 수와 목록 occurrence 수가 다르게 보일 수 있다. badge는 중복을 제거한 target 관계 수를 읽고, 목록에서는 실제 원문 위치를 각각 검토한다.

6. 깨진 링크 위치를 연다

  1. 깨진 링크 section을 펼친다.
  2. 복구 계획 항목 아래 target이 missing-recovery-plan.md인지 확인한다.
  3. 항목을 선택한다.
  4. editor가 현재 문서의 해당 link line을 강조하는지 확인한다.

깨진 링크 항목을 선택해 focus 문서의 해당 Markdown link 위치를 강조한 화면

항목 선택은 존재하지 않는 target 문서를 새로 만들거나 자동으로 가장 비슷한 문서에 연결하지 않는다. 수정 권한은 사용자에게 남기고, 정확한 원문 위치까지만 안내한다.

7. target을 명시적으로 고친다

fixture에는 실제 대상인 recovery-plan.md가 이미 있다. 강조된 line에서 target만 다음처럼 바꾼다.

- - [복구 계획](missing-recovery-plan.md)
+ - [복구 계획](recovery-plan.md)

저장 뒤 Link Map으로 돌아가 인덱스 완료를 기다린다. 예상 변화는 다음과 같다.

항목 수정 전 수정 후
백링크 2 2
포워드 링크 1 2
깨진 링크 1 0
로컬 그래프 node 4 5

백링크는 다른 문서의 원문이 바뀌지 않았으므로 그대로다. target이 해결되면서 깨진 링크 하나가 포워드 링크와 graph node로 이동한다.

⚠️
이름이 비슷하다는 이유로 임의의 target을 선택하지 않는다. intended document가 불명확하면 작성자나 history를 확인하고, 대체 문서가 없다면 새 문서를 만들지 기존 link를 제거할지 먼저 결정한다.

전체 조작 영상

다음 7.1초 영상은 focus.md에서 launcher로 Link Map을 열고, 세 방향 count와 4-node 로컬 그래프를 확인하고, backlink·forward 원문 목록을 읽은 뒤 깨진 링크를 눌러 해당 문장 위치로 이동하는 흐름을 실제 Glif에서 보여 준다. 파란 원과 아래 자막은 캡처 안내이며 문서에는 저장되지 않는다.

숫자가 예상과 다를 때

증상 먼저 확인할 것 조치
모든 count가 0이다 활성 문서와 Scope focus.md를 다시 열고 link-health가 현재 Scope인지 확인
인덱스 재구성 중이 오래 지속된다 Scope 접근과 파일 읽기 오류 다른 panel로 이동하지 말고 완료를 기다린 뒤, 실패 log가 있으면 Scope를 다시 연다
backlink가 하나 부족하다 incoming 문서 target과 저장 여부 focus.md 철자·상대 path를 확인하고 두 문서를 저장
포워드 링크가 깨진 링크로 나온다 target 파일 존재와 기준 폴더 상대 path가 현재 문서 위치를 기준으로 실제 파일에 도달하는지 확인
깨진 항목을 눌러도 예상 line이 아니다 같은 target의 여러 occurrence 강조된 label·href를 읽고 목록의 다른 occurrence 확인
graph node가 count 합계와 다르다 같은 문서가 양방향인지, 깨진 target인지 graph는 해결된 고유 문서 node를 그리므로 방향별 수의 단순 합과 다를 수 있음
외부 URL이 깨진 링크에 없다 로컬 문서 검사와 외부 URL 검사의 차이 publish preflight 또는 URL 검사 흐름 사용

완료 확인

  • focus.md가 현재 문서이고 인덱스 완료인지 확인했다.
  • 백링크 2, 포워드 링크 1, 깨진 링크 1을 방향별로 설명할 수 있다.
  • 로컬 그래프의 네 node 이름과 방향을 확인했다.
  • graph가 Scope 전체가 아니라 현재 문서의 직접 관계임을 이해했다.
  • backlink·forward 목록에서 실제 원문 문맥을 확인했다.
  • 깨진 링크 항목을 눌러 현재 문서의 해당 line으로 이동했다.
  • target을 고친 뒤 인덱스 완료 상태에서 count 변화를 다시 확인했다.

다음 단계에서는 같은 Link Map의 중복 검토, 추천과 미연결 언급을 사용자 검토 흐름으로 이어 간다. 자동 병합이나 자동 적용이 아니라 후보별 명시적 action을 다룬다.