위키링크 자동완성

위키링크는 현재 문서에서 다른 Markdown 문서를 빠르게 가리키는 짧은 참조다. Glif에서 일반 [[를 입력하면 현재 Scope의 문서 title, alias와 path를 바탕으로 후보가 나타난다. 정확한 파일 경로를 외우거나 Shelf를 오가며 복사하지 않아도 된다.

[[메타데이터 사전]]
[[wikilink/guides/aurora]]

첫 번째 형태는 Scope에서 고유한 title을 사용한다. 두 번째 형태는 같은 title을 가진 문서가 둘 이상일 때 선택한 문서를 안전하게 구분하는 경로를 사용한다. 두 형태 모두 Markdown 원문에 그대로 남는다.

이 장의 실증 프로젝트는 다음 네 파일로 구성된다.

1. 자동완성이 열리는 위치를 구분한다

문서 후보 자동완성은 일반 위키링크의 문서 target을 입력할 때 열린다.

입력 상태	결과
`[[`	현재 문서 외의 문서 후보를 표시
`[[오로`	title, alias 또는 path가 입력과 맞는 후보로 좁힘
`[[문서#`	문서 후보 선택 단계가 끝난 상태; heading anchor 자동완성 영역
`[[문서\|표시 이름`	label을 쓰는 영역이므로 문서 후보를 다시 열지 않음
`![[`	embed 문법이므로 일반 위키링크 문서 후보와 구분
inline code 또는 fenced code 안의 `[[`	예제 code를 바꾸지 않도록 자동완성을 열지 않음

선택 영역이 여러 개이거나 text가 선택된 상태에서도 문서 자동완성은 source를 임의로 바꾸지 않는다. 먼저 한 곳에 caret만 둔 뒤 입력한다.

ℹ️

자동완성은 현재 Scope에서 알고 있는 문서 후보를 돕는다. 임의의 문자열을 문서로 추론하거나 다른 Scope의 문서를 자동으로 연결하는 기능은 아니다. 새로 만들거나 이름을 바꾼 문서가 보이지 않으면 현재 Scope에서 변경이 반영됐는지 확인한 뒤 후보를 다시 연다.

2. `[[`를 입력하고 후보를 읽는다

예제 Scope를 연다.
wikilink/workbench.md를 연다.
Markdown 원문 보기로 전환한다.
자동완성: 뒤에 [[오로라 배포를 입력한다.
후보의 큰 글자는 title, 오른쪽 보조 text는 문서 path인지 확인한다.

이번 예제에는 title이 오로라 배포 가이드인 문서가 두 개 있다.

wikilink/archive/aurora.md
wikilink/guides/aurora.md

title만 보고 선택하면 어느 문서인지 알 수 없으므로 path를 함께 읽는다. archive는 이전 절차, guides는 현재 운영 문서다. 자동완성에서 보이는 path는 후보 구분 정보이며, 사용자 PC의 절대 경로를 공개 문서에 넣는 것이 아니다.

3. 키보드로 후보를 선택한다

자동완성 목록은 editor 안의 표준 키보드 흐름을 사용한다.

키	동작
`↑`, `↓`	이전·다음 후보 선택
`Enter`	선택한 후보 삽입
`Tab`	현재 선택을 확정할 수 있는 completion key
`Escape`	source를 바꾸지 않고 목록 닫기
`Ctrl+Z`	방금 적용한 completion transaction 되돌리기

↓로 wikilink/guides/aurora.md 후보를 고르고 Enter를 누르면 이번 실증에서는 다음 source가 삽입됐다.

[[wikilink/guides/aurora]]

Glif는 같은 title이 여러 문서를 가리킬 때 title 하나를 임의로 선택하지 않는다. 선택한 문서를 구분할 수 있는 안전한 Scope 기준 path를 쓰고 .md 확장자는 생략한다. 이 때문에 문서가 다른 폴더에 있어도 target이 명확하다.

4. 자동완성 선택을 한 단계 되돌린다

후보 선택은 일반 editor history에 한 transaction으로 들어간다. Ctrl+Z를 한 번 누르면 선택으로 교체된 target만 되돌아가고, 선택 전 입력하던 query가 복구된다.

이번 예제의 변화는 다음과 같다.

선택 전: [[오로라 배포
선택 후: [[wikilink/guides/aurora]]
Undo 후: [[오로라 배포

Undo 뒤 다른 후보를 고르거나 query를 더 입력할 수 있다. Escape로 목록만 닫았을 때는 Markdown이 바뀌지 않으므로 되돌릴 source 변경도 없다.

5. alias로 문서를 찾는다

title과 파일 이름이 떠오르지 않을 때는 문서 frontmatter의 alias를 입력할 수 있다. 예제 wikilink/reference/glossary.md는 다음 metadata를 가진다.

title: 메타데이터 사전
aliases:
  - 용어집

작업대에서 [[용어를 입력하면 메타데이터 사전 후보가 나타난다.

후보 title은 메타데이터 사전, 보조 path는 wikilink/reference/glossary.md다. alias는 찾기 위한 key이고, Scope에서 title이 고유하고 위키 target으로 안전하면 삽입 결과는 읽기 쉬운 canonical title을 사용한다.

[[메타데이터 사전]]

alias 자체를 표시 label로 유지해야 한다면 completion 뒤 위키링크 label 문법을 명시적으로 작성한다. 자동완성은 문서 identity를 안전하게 연결하는 일을 우선하며, 사용자가 의도하지 않은 별칭 표현을 임의로 만들지 않는다.

6. title, alias와 path의 선택 우선순위를 이해한다

입력과 후보는 다음 관점으로 좁혀진다.

title이 정확히 같은 문서
title이 입력으로 시작하는 문서
alias가 입력으로 시작하는 문서
path에 입력이 포함된 문서

같은 수준의 후보는 path를 함께 보여 주므로 폴더 문맥으로 구분할 수 있다. 현재 열어 둔 작업대 자체는 자기 자신을 가리키는 기본 후보에서 제외된다. 후보가 많다면 목록 전체를 훑기보다 title이나 path 일부를 더 입력해 좁히는 편이 빠르다.

상황	삽입 target	이유
고유하고 안전한 title	`[[메타데이터 사전]]`	읽기 쉽고 문서 identity가 하나뿐임
같은 title이 여러 문서에 존재	`[[wikilink/guides/aurora]]`	선택한 문서를 path로 명확히 구분
title에 위키 target 구분 문자가 포함	안전한 path 후보	문법을 깨는 target을 만들지 않음
현재 문서	기본 후보에서 제외	실수로 자기 자신을 연결하는 마찰 감소

전체 조작 영상

다음 6.8초 영상은 동명 title 후보 두 개 확인, ↓+Enter로 정확한 path 삽입, 한 단계 Undo, alias 검색과 고유 title 삽입을 실제 Glif에서 이어서 수행한다. 파란 원과 아래 자막은 캡처 안내이며 Markdown에는 저장되지 않는다.

문제 해결

증상	확인할 것	해결
`[[`를 입력해도 목록이 열리지 않는다	실시간 미리보기가 아닌 Markdown 원문인지, caret 하나인지	원문 보기에서 선택을 해제하고 일반 text 위치에 다시 입력
code 예제 안에서 목록이 열리지 않는다	inline code 또는 fenced code 내부인지	실제 link를 만들 문장 밖에서 입력; code 보호 동작은 정상
원하는 문서가 없다	같은 Scope에 있는 Markdown 문서인지	Scope와 문서 존재를 확인하고 title·alias·path 일부로 다시 검색
동명 문서를 구분하기 어렵다	후보 오른쪽 path	현재 문서는 `guides`, 이전판은 `archive`처럼 폴더 문맥 확인
선택 뒤 예상과 다른 짧은 title이 들어갔다	title이 Scope에서 고유한지	후보 path로 대상 확인; 동명 충돌이 있으면 자동으로 path target 사용
`Enter`가 문서를 삽입하지 않는다	목록에서 선택 상태가 있는지	`↑` 또는 `↓`로 후보를 선택한 뒤 `Enter`
잘못된 후보를 골랐다	선택 직후인지	`Ctrl+Z` 한 번으로 query를 복구하고 다른 후보 선택
목록만 닫고 싶다	source 변경을 원하지 않는지	`Escape`를 눌러 Markdown을 유지한 채 닫기
embed를 만들고 싶다	일반 `[[`를 입력했는지	`![[...]]` embed 흐름 또는 문맥 메뉴의 embed 복사 사용

완료 확인

일반 Markdown text에서 [[를 입력해 문서 후보를 열었다.
후보의 title과 path를 함께 읽었다.
동명 title 두 개 중 의도한 폴더의 문서를 골랐다.
동명 문서는 확장자 없는 상대 path target으로 삽입됐다.
Ctrl+Z 한 번으로 선택 전 query를 복구했다.
alias 용어집으로 메타데이터 사전을 찾았다.
고유 title은 읽기 쉬운 [[메타데이터 사전]]으로 삽입됐다.
Escape와 code 영역의 fail-safe 경계를 이해했다.

이제 검색, 정확한 block·section 참조, 위키링크 작성까지 하나의 연결 흐름으로 사용할 수 있다.