자동 링크를 안전하게 적용하기

자동 링크는 현재 Scope의 문서 title과 alias를 찾아 사용자가 명시적으로 실행했을 때만 현재 문서의 Markdown 원문에 일반 링크를 기록한다. 모든 언급을 빠짐없이 연결하는 AI 기능이나 background rewrite가 아니다. 문서당·문단당 제한과 제외 정책을 먼저 정하고, 적용 결과를 source와 rendered view에서 검토한 뒤 필요하면 한 번에 되돌리는 보수적 편집 도구다.

이 장에서는 다음 결과를 만든다.

적용 전: 메타데이터: 문서를 찾기 쉽게 만든다.
적용 후: [메타데이터](concepts/metadata.md): 문서를 찾기 쉽게 만든다.

실습 파일은 네 개다.

1. 자동 링크와 위키링크 자동완성을 구분한다

두 기능은 같은 문서 index를 활용하지만 시작점과 결과가 다르다.

기능	시작	결과	적합한 상황
위키링크 자동완성	`[[`를 입력하고 후보를 직접 선택	`[[target]]`	새 참조를 한 곳에 정확히 작성할 때
자동 링크	정책을 정한 뒤 현재 문서 적용을 실행	`[표시 text](relative/path.md)`	이미 작성된 여러 언급을 제한적으로 연결할 때

자동 링크는 적용 전까지 원문을 바꾸지 않는다. 적용 결과는 Glif 전용 placeholder가 아니라 일반 Markdown 링크이므로 다른 editor와 Hugo에서도 읽을 수 있고, 이후 직접 고치거나 삭제할 수 있다.

⚠️

자동 링크는 전체 Scope를 일괄 rewrite하지 않는다. 실행 시점의 현재 문서 한 개만 바뀐다. 문서 집합 전체를 바꿀 목적으로 반복 실행하기 전에 각 문서의 diff와 목적지를 개별 확인한다.

2. 정책을 먼저 설정한다

상단의 설정을 연다.
왼쪽에서 에디터를 선택한다.
자동링크 section으로 이동한다.
전체 사용 여부, 문서당·문단당 최대 수와 제외 정책을 정한다.

이번 실증 설정은 다음과 같다.

설정	실증 값	입력 범위·의미
자동링크 사용	켬	preview, publish와 명시적 source 적용에 같은 정책을 사용
문서당 최대 링크 수	2	같은 target을 현재 문서에서 새로 연결할 최대 수, `1`~`10`
문단당 최대 링크 수	1	같은 target을 한 block에서 새로 연결할 최대 수, `1`~`5`
헤딩 제외	켬	heading text를 자동으로 link로 바꾸지 않음
테이블 제외	켬	table cell text를 자동으로 link로 바꾸지 않음
중복 후보 건너뛰기	켬	한 key가 여러 문서를 가리키면 자동 선택하지 않음

기본값은 자동 링크 사용, 문서당 3, 문단당 1, heading·table·code 제외와 중복 후보 건너뛰기다. 이 장에서는 제한 동작을 한 화면에서 확인하기 위해 문서당 값을 2로 낮춘다.

전체 기능을 잠시 끄기

자동링크 사용을 끄면 나머지 숫자와 제외 정책은 보존되지만 새 후보를 적용하지 않는다. 특정 문서를 편집하는 동안 어떤 자동 링크 제안도 사용하지 않으려면 세부 값을 지우는 대신 전체 switch를 끈다.

다시 켜면 이전 제한과 제외 정책으로 돌아온다. 전체 off는 문서를 rewrite하거나 기존 Markdown 링크를 제거하지 않는다.

3. 예제에서 연결 가능한 후보를 확인한다

autolink/workbench.md에는 메타데이터가 여러 번 등장하고, 오로라는 서로 다른 두 문서의 공통 alias다.

# 메타데이터와 오로라 연결 계획

메타데이터: 문서를 찾기 쉽게 만든다. 메타데이터, 같은 문단의 반복 언급이다. 메타데이터.

메타데이터: 두 번째 문단에서는 문서당 제한 안에서 한 번 더 연결한다.

메타데이터: 세 번째 문단은 문서당 최대 링크 수를 넘으므로 일반 text로 남는다.

오로라: 같은 alias를 가진 문서가 둘이므로 자동으로 추측하지 않는다.

이번 정책에서 새 link가 될 수 있는 언급은 첫째·둘째 문단의 첫 메타데이터 두 개다.

한 문단에서는 같은 target을 한 번만 연결한다.
같은 문서에서는 같은 target을 두 번까지만 연결한다.
heading의 메타데이터는 제외한다.
세 번째 문단은 문서당 최대 수를 이미 채웠으므로 남긴다.
오로라는 두 target 중 하나를 추측하지 않는다.

4. 보호되는 source 영역을 이해한다

자동 링크는 단어가 보인다는 이유만으로 모든 source range를 감싸지 않는다.

영역	이번 결과	이유
heading	유지	헤딩 제외가 켜져 있음
일반 paragraph	제한 안에서 연결	기본 후보 적용 영역
table	유지	테이블 제외가 켜져 있음
inline code와 fenced code	유지	예제와 명령 text를 바꾸지 않는 고정 보호 경계
기존 Markdown link	유지	link 안에 link를 다시 만들지 않음
image, HTML, definition	유지	기존 Markdown 구조를 중첩 rewrite하지 않음

예제의 마지막 두 영역은 다음처럼 그대로 남는다.

`메타데이터` code와 [메타데이터](concepts/metadata.md) 기존 link는 다시 감싸지 않는다.

| 구분 | 용어 |
| :--- | :--- |
| 기준 | 메타데이터 |
| 조직 | 오로라 |

code 제외는 현재 고정 보호 동작이다. 설정 화면에 별도 switch가 보이지 않더라도 code text를 일반 prose처럼 자동 변환한다고 가정하지 않는다.

5. 현재 문서에 명시적으로 적용한다

autolink/workbench.md를 연다.
상단 editor action의 추가 작업을 연다.
현재 문서에 자동링크 적용을 선택한다.
성공 알림의 적용 개수를 확인한다.

명령 팔레트에서 자동링크 적용을 검색해 같은 작업을 실행할 수도 있다. 어느 진입점을 사용해도 범위는 현재 문서이며, 같은 설정을 사용한다.

이번 실증에서는 다음 알림을 확인했다.

2개의 자동링크를 현재 문서에 반영했습니다.

적용된 핵심 diff는 다음과 같다.

-메타데이터: 문서를 찾기 쉽게 만든다. 메타데이터, 같은 문단의 반복 언급이다. 메타데이터.
+[메타데이터](concepts/metadata.md): 문서를 찾기 쉽게 만든다. 메타데이터, 같은 문단의 반복 언급이다. 메타데이터.

-메타데이터: 두 번째 문단에서는 문서당 제한 안에서 한 번 더 연결한다.
+[메타데이터](concepts/metadata.md): 두 번째 문단에서는 문서당 제한 안에서 한 번 더 연결한다.

target은 source 문서 위치를 기준으로 계산한 상대 Markdown path다. 작업대와 target이 모두 autolink/ 아래에 있으므로 concepts/metadata.md가 기록된다. 사용자 PC의 절대 경로는 Markdown에 들어가지 않는다.

6. 모호한 alias는 직접 선택한다

예제에서 오로라는 다음 두 문서를 모두 가리킨다.

autolink/teams/aurora.md
autolink/archive/aurora.md

중복 후보 건너뛰기가 켜져 있으면 자동 링크는 어느 쪽도 선택하지 않는다.

오로라: 같은 alias를 가진 문서가 둘이므로 자동으로 추측하지 않는다.

이 문장을 연결해야 한다면 위키링크 자동완성에서 후보 path를 읽고 직접 선택하거나, 일반 Markdown 링크를 작성한다.

[오로라](teams/aurora.md)

중복 후보 건너뛰기를 꺼도 자동 링크가 문서 의미를 이해해 올바른 대상을 보장하는 것은 아니다. 동명·동일 alias가 의도된 정보 구조라면 switch를 유지하고 수동 선택하는 편이 안전하다.

7. 렌더 결과와 일반 text 경계를 검토한다

적용 후 실시간 미리보기 보기로 전환해 link와 남은 text를 함께 확인한다.

다음 항목을 순서대로 본다.

새 link text가 원래 단어와 같은가?
link를 열었을 때 메타데이터 문서로 이동하는가?
첫 문단의 두 번째·세 번째 언급이 일반 text로 남았는가?
세 번째 문단이 문서당 제한 때문에 남았는가?
오로라, code, 기존 link와 table이 유지됐는가?

source만 보면 문법은 확인할 수 있지만 target 문서의 내용이 의도와 맞는지는 알 수 없다. 중요한 문서는 새 link를 한 번 열어 목적지를 확인한다.

8. 적용 전체를 한 번에 되돌린다

자동 링크 적용은 editor의 한 편집 단계다. 적용 직후 editor에서 Ctrl+Z를 한 번 누르면 이번 실행이 만든 두 link가 함께 사라지고 적용 전 본문으로 돌아간다.

적용: 일반 text 두 곳 → Markdown link 두 곳
Undo 1회: 두 link → 적용 전 일반 text

Undo는 기존 수동 링크나 설정을 삭제하지 않는다. 적용 전에 존재했던 [메타데이터](concepts/metadata.md)는 그대로 남고, 이번 transaction이 만든 두 곳만 복구된다.

ℹ️

적용 후 다른 편집을 여러 번 수행했다면 Ctrl+Z는 가장 최근 transaction부터 되돌린다. 자동 링크 diff만 취소하려면 적용 직후 결과를 검토하고 바로 Undo하는 흐름이 가장 명확하다.

9. 반복 적용과 수동 편집

이미 만들어진 Markdown link는 다시 후보가 되지 않는다. 같은 설정과 같은 원문에 반복 적용해도 기존 link를 중첩하지 않는다. 추가 적용이 생길 수 있는 경우는 다음과 같다.

문서당 또는 문단당 제한을 높였다.
heading·table 제외를 바꿨다.
새 문서를 만들거나 title·alias를 바꿨다.
일반 text를 새로 작성했다.
모호했던 key가 문서 정리로 고유해졌다.

변경이 없으면 다음 안내가 나타난다.

현재 문서에 적용할 자동링크가 없습니다.

자동 링크 적용 후에도 결과는 일반 Markdown이므로 link label이나 path를 직접 바꿀 수 있다.

[메타데이터 설명](concepts/metadata.md)

수동으로 수정한 link는 이후 자동 적용이 덮어쓰지 않는다.

전체 조작 영상

다음 9.5초 영상은 정책 확인, 전체 off/on, 적용 전 원문, 추가 작업 → 현재 문서에 자동링크 적용, 적용 후 source·rendered result, Ctrl+Z 한 번의 전체 복구를 실제 Glif에서 이어서 수행한다. 파란 원과 아래 자막은 캡처 안내이며 문서에는 저장되지 않는다.

문제 해결

증상	확인할 것	해결
적용 개수가 `0`이다	전체 switch, 현재 문서의 title·alias 언급	자동링크를 켜고 target 문서가 같은 Scope에 있는지 확인
예상보다 적게 연결된다	문서당·문단당 최대 수	현재 값과 이미 적용된 link를 확인하고 필요한 경우 제한을 조정
heading이 연결되지 않는다	헤딩 제외	heading link가 정말 필요한 경우에만 switch를 끄고 diff를 검토
table cell이 연결되지 않는다	테이블 제외	구조 table을 보호하는 동작; 필요한 cell은 수동 link 작성
code가 연결되지 않는다	inline/fenced code인지	code 보호는 정상이며 prose 영역에 link 작성
`오로라` 같은 alias가 남는다	같은 key를 가진 문서가 둘 이상인지	후보 path를 읽고 위키링크 자동완성 또는 수동 link 사용
다른 문서까지 바뀔까 걱정된다	명령 이름과 active document	적용 범위는 현재 문서 한 개; 실행 전 header title 확인
잘못된 link가 만들어졌다	적용 직후인지	`Ctrl+Z` 한 번으로 이번 transaction을 되돌리고 설정 조정
다시 실행해도 변화가 없다	이미 Markdown link인지	중첩 방지 동작은 정상; 새 일반 text나 정책 변화가 있는지 확인
새 title이 후보가 되지 않는다	Scope index 반영 여부	문서를 저장하고 같은 Scope인지 확인한 뒤 다시 실행

완료 확인

자동 링크가 background rewrite가 아니라 현재 문서의 명시적 source mutation임을 이해했다.
전체 on/off를 전환하고 기존 세부 값이 유지되는지 확인했다.
문서당 최대 수를 2, 문단당 최대 수를 1로 설정했다.
heading과 table 제외를 켰다.
동일 alias 오로라가 자동 선택되지 않는 것을 확인했다.
현재 문서 적용으로 메타데이터 link 두 개를 만들었다.
code, 기존 link와 table이 그대로인지 source에서 확인했다.
rendered view에서 새 link 목적지와 남은 일반 text를 검토했다.
Ctrl+Z 한 번으로 이번 적용 전체를 복구했다.
같은 원문에 반복 적용해 link가 중첩되지 않는 경계를 이해했다.

자동 링크를 적용한 뒤에는 link 수보다 관계의 정확성을 우선한다. 모호한 후보는 직접 선택하고, 자동으로 만든 link도 중요한 문서에서는 목적지를 열어 확인한다.