문단·섹션 link와 embed

문서 전체를 가리키는 것만으로는 충분하지 않을 때가 있다. 긴 회의록의 한 문단, 사양서의 특정 section, 여러 장에서 반복해 보여 줄 기준 문구처럼 정확한 원문 위치가 필요한 경우다. Glif는 현재 문단과 heading section에 안정적인 anchor를 만들거나 기존 anchor를 재사용해 link와 embed 문법을 복사한다.

link: 원문 위치로 이동하는 참조다.
embed: 같은 원문을 현재 문맥 안에서 보여 주는 참조다.
둘 다 원문 복사본을 만들지 않는다. 원본 Markdown 하나가 identity의 기준이다.

이 문서에서는 다음 두 파일을 사용한다.

원문 파일은 아래 두 위치를 참조 대상으로 제공한다.

# 오로라 참조 원문

## 핵심 원칙

오로라 가이드의 검색 계약은 결과 문맥과 원문 위치를 함께 보존한다.

링크는 원문 위치를 가리키고, embed는 같은 원문을 현재 문맥에서 보여 준다.

1. link와 embed를 선택한다

필요한 결과	사용할 기능	복사되는 형태
문단을 클릭해 원문 위치로 이동	현재 문단 링크 복사	`[문단 요약](/문서.md#block-id)`
section을 클릭해 heading으로 이동	현재 섹션 링크 복사	`[heading](/문서.md#heading-anchor)`
문서 전체를 현재 문맥에 표시	현재 문서 임베드 복사	`![[/문서.md]]`
한 section만 현재 문맥에 표시	현재 섹션 임베드 복사	`![[/문서.md#heading-anchor]]`
한 문단만 현재 문맥에 표시	현재 문단 임베드 복사	`![[/문서.md#block-id]]`

link는 독자가 원문으로 이동해야 할 때 적합하다. embed는 원문 내용을 현재 문서의 흐름 안에서 바로 읽어야 할 때 적합하다. 같은 문장을 여러 파일에 복사해 붙여 넣는 대신 embed를 사용하면 수정 기준이 한 원문에 남는다.

2. 문단·섹션 메뉴를 연다

reference-source.md를 Glif에서 연다.
실시간 미리보기에서 참조할 문단 위에 포인터를 둔다.
우클릭해 문맥 메뉴를 연다.
link, embed 또는 원문 위치 열기 action을 선택한다.

메뉴에는 다음 action이 같은 위치에 모여 있다.

현재 섹션 링크 복사
현재 문단 링크 복사
현재 앵커 링크 대상 열기
현재 문서 임베드 복사
현재 섹션 임베드 복사
현재 문단 임베드 복사
현재 링크를 임베드로 전환

현재 앵커 링크 대상 열기는 커서 아래에 내부 Markdown anchor link가 있을 때 사용한다. 일반 문장 위에서는 열 대상이 없으므로 link 또는 embed 복사 action을 사용한다.

3. 현재 문단 link를 복사한다

원문의 첫 문단을 우클릭하고 현재 문단 링크 복사를 선택한다. Glif는 현재 문단에 block id가 없으면 새 id를 만들고 Markdown에 저장한다.

이번 실증에서 복사된 값은 다음과 같다.

[오로라 가이드의 검색 계약은 결과 문맥과 원문 위치를 함께 보존한다.](/reference-source.md#glif-p-1)

원문에는 아래 marker가 문단 바로 앞에 추가됐다.

<!-- glif:block-id: glif-p-1 -->
오로라 가이드의 검색 계약은 결과 문맥과 원문 위치를 함께 보존한다.

block id는 표시용 별도 데이터베이스에만 있는 값이 아니다. Markdown comment이므로 파일을 다른 도구에서 열어도 문단 본문을 방해하지 않으면서 참조 identity를 보존한다. 같은 문단에서 다시 복사하면 기존 id를 재사용한다.

⚠️

block id marker를 수동으로 삭제하거나 중복시키면 기존 참조가 깨지거나 다른 문단을 가리킬 수 있다. 문단을 옮길 때는 marker와 본문을 함께 이동하고, 단순 정리 목적으로 marker만 제거하지 않는다.

4. 현재 섹션 link를 복사한다

핵심 원칙 heading 또는 그 아래 본문을 우클릭하고 현재 섹션 링크 복사를 선택한다. anchor가 없다면 heading에 명시적인 id가 추가된다.

## 핵심 원칙 {#section}

이번 실증에서 복사된 section link는 다음과 같다.

[핵심 원칙](/reference-source.md#section)

문단 link가 한 block을 가리키는 것과 달리 section link는 해당 heading에서 다음 같은 레벨 heading 전까지의 구조를 가리킨다. heading 제목을 바꿀 때도 명시적 {#section}을 유지하면 기존 참조 identity를 보존할 수 있다.

자동 anchor 이름을 그대로 써야 하는 이유

Glif가 생성한 anchor는 현재 문서에서 충돌하지 않는 값을 선택한다. 사람이 보기 좋은 이름으로 다시 고치고 싶다면 이미 붙여 넣은 모든 link와 embed의 fragment도 함께 바꿔야 한다. 공개 문서나 여러 작업대에서 사용한 뒤에는 기존 id 유지가 안전하다.

5. 문서·섹션·문단 embed를 복사한다

같은 문맥 메뉴에서 대상 범위에 맞는 embed action을 고른다. 이번 실증에서 실제로 복사된 세 문법은 다음과 같다.

![[/reference-source.md]]
![[/reference-source.md#section]]
![[/reference-source.md#glif-p-1]]

문법	렌더 범위
`![[/reference-source.md]]`	문서 전체
`![[/reference-source.md#section]]`	`핵심 원칙` section
`![[/reference-source.md#glif-p-1]]`	지정 문단 한 개

/로 시작하는 경로는 현재 Binder root 기준이다. 다른 폴더의 작업대로 옮겨도 같은 Binder 안에서는 동일한 원문 identity를 가리킨다. Binder가 다르거나 대상 문서가 포함되지 않은 출력에서는 참조 해석 경계가 달라질 수 있으므로 게시 전 preview를 확인한다.

6. 작업대에 붙여 넣고 원문과 비교한다

reference-workbench.md를 연다.
Markdown 원문 보기로 전환한다.
문단 link, 섹션 link와 세 embed를 붙여 넣는다.
저장된 path와 fragment가 원문에서 만든 값과 같은지 확인한다.
실시간 미리보기로 돌아간다.

실시간 미리보기에서는 link가 클릭 가능한 참조로, embed가 현재 문맥 안의 원문 preview로 바뀐다.

embed 화면이 원문을 복제한 새 문서처럼 보여도 저장 구조는 다르다. 작업대에는 ![[...]] 참조 문법만 있고 실제 본문은 reference-source.md에 남는다.

7. 렌더된 참조에서 원문 위치로 돌아간다

작업대의 문단 link 위에서 우클릭한다.
현재 앵커 링크 대상 열기를 선택한다.
열린 탭 이름이 reference-source인지 확인한다.
glif-p-1 marker 다음 문단이 활성 위치로 강조되는지 확인한다.

section link에서 같은 action을 실행하면 #section heading으로 이동한다. 대상 문서만 열리고 정확한 위치가 보이지 않으면 anchor가 원문에 존재하는지, path와 fragment가 현재 Binder 기준으로 해석되는지 확인한다.

전체 조작 영상

다음 영상은 문단 메뉴 열기, block id 저장, link·embed 문법 확인, embed 렌더링과 원문 위치 복귀를 9.2초로 묶은 실제 Glif 조작이다. 파란 원과 아래 자막은 캡처용 안내이며 원문에 저장되지 않는다.

원문을 바꿀 때의 영향

변경	예상 결과	안전한 처리
문단 text만 수정	같은 block id를 유지하면 참조가 새 내용을 가리킴	marker를 함께 보존
문단 위치 이동	marker와 문단을 함께 옮기면 identity 유지	두 줄을 한 block으로 이동
heading 제목 수정	명시적 anchor를 유지하면 기존 참조 유지	`{#anchor}` 보존
파일 이름·경로 수정	path 기반 link/embed 갱신 필요	Glif의 rename·reference rewrite 결과 검토
anchor 삭제	해당 fragment를 쓰는 참조가 unresolved	backlink·link health에서 사용처 확인 후 변경
문서 삭제	문서·section·문단 참조가 모두 unresolved	삭제 전 참조 관계와 대체 원문 확인

문제 해결

증상	확인할 것	복구
문단 link를 복사할 수 없다	커서가 실제 본문 문단 위인지	표·빈 줄·heading이 아닌 문장 위에서 다시 연다
섹션 link가 다른 heading을 가리킨다	우클릭 위치와 가장 가까운 상위 heading	대상 heading 또는 그 section 본문에서 다시 복사한다
embed가 원문 대신 unresolved 상태다	Binder root 기준 path, 파일 존재, anchor 존재	같은 Binder에 대상 파일을 포함하고 path·fragment를 고친다
문서 전체가 표시돼 너무 길다	문서 embed를 사용했는지	section 또는 문단 embed로 범위를 좁힌다
원문 열기가 문서 첫 줄에 머문다	fragment와 원문의 explicit anchor	marker를 복구하거나 현재 위치에서 새 참조를 복사한다
같은 내용을 두 군데서 따로 수정하게 된다	text copy를 사용했는지 embed를 사용했는지	단일 원문을 정하고 다른 위치는 embed로 교체한다

완료 확인

문단 link 복사 뒤 glif:block-id가 원문에 저장됐다.
같은 문단에서 다시 복사해 기존 block id를 재사용했다.
section link와 heading explicit anchor가 서로 일치한다.
문서·section·문단 embed 세 문법을 작업대에 붙여 넣었다.
embed가 원문 복사본이 아닌 참조 문법으로 저장됐다.
렌더된 link에서 원문 문서의 정확한 block 또는 heading으로 돌아갔다.
fixture를 원상 복구하거나 자신의 실습 문서 변경을 의도적으로 저장했다.

다음에는 [[ 자동완성으로 문서 제목·alias·path 후보를 선택하는 흐름을 다룬다.