문서를 드롭해 링크·임베드·본문으로 삽입하기

문서를 편집기에 드롭하면 Glif는 곧바로 내용을 삽입하지 않는다. 먼저 문서 드롭 메뉴를 열어 링크, 참조 보기, 임베드, 본문 복사 중 원하는 결과를 고르게 한다. 같은 드래그라도 선택한 intent에 따라 Markdown에 저장되는 내용과 원문과의 관계가 달라지기 때문이다.

한 번의 드래그가 네 종류의 결과로 갈리는 이유

문서를 놓는 행위는 “이 문서를 여기서 사용한다”는 의도만 전달한다. Glif는 그 뒤 다음 선택을 요구한다.

링크·참조 보기·임베드는 원본과의 관계를 남긴다. 본문 복사는 현재 시점의 내용을 복제하므로 원본과 목적 문서가 이후 서로 달라질 수 있다. 이 차이를 확인하지 않고 드롭 즉시 한 종류로 고정하면 사용자가 원하지 않은 결합이나 중복을 만들 수 있다.

실습 파일

다음 네 파일을 같은 폴더에 내려받고 그 폴더를 Scope로 연다.

• 재사용할 원문
• 링크 삽입 대상
• 임베드 삽입 대상
• 본문 복사 대상

reusable-source.md에는 front matter와 H1·H2·목록·문단이 있다. 세 대상 문서에는 결과:라는 삽입 위치가 준비되어 있다. 공개 fixture 자체는 바꾸지 말고 사본을 만들어 실습하면 세 결과를 반복 비교하기 쉽다.

드롭을 시작하기 전에

1. 목적 문서를 편집기에서 연다.
2. Shelf가 보이지 않으면 상단 작업 메뉴에서 Shelf를 연다.
3. 목적 문서의 결과: 뒤가 화면에 보이도록 한다.
4. Shelf에서 reusable-source를 찾는다.
5. 원문과 목적 문서가 같은 Scope 또는 Glif가 해석할 수 있는 workspace 경계에 있는지 확인한다.

폴더나 경계를 알 수 없는 물리 경로는 문서 payload로 취급하지 않는다. 이동식 mount처럼 workspace 가상 경로가 있는 문서는 그 경로를 기준으로 link를 계산한다.

1. 문서를 삽입 위치로 드래그한다

link-destination.md를 열고 Shelf의 reusable-source를 결과: 뒤로 드래그한다.

포인터가 편집기 안에 들어오면 drop effect는 복사로 표시된다. 실제 삽입 위치는 포인터 좌표에서 계산되므로 문단 중간보다 빈 줄이나 결과: 뒤처럼 경계가 분명한 곳에 놓는 편이 안전하다.

문서를 놓으면 다음 메뉴가 열린다.

메뉴에는 다음 항목이 있다.

• 링크로 삽입
• 계층도·마인드맵·칸반·표·차트·간트·페이지·계산로그·슬라이드 미리보기 참조 보기로 삽입
• 임베드로 삽입
• 본문으로 삽입 (중복 생성)

메뉴 바깥을 누르거나 Esc를 누르면 아무것도 삽입하지 않고 닫는다. 드롭만으로 문서가 바뀌지 않는다는 점이 중요하다.

2. 링크로 삽입한다

링크로 삽입을 선택한다. 같은 폴더의 문서이므로 목적 파일에는 다음 Markdown이 저장된다.

[재사용 가능한 원문](reusable-source.md)

링크의 표시 제목은 drag payload의 문서 제목을 사용한다. 경로는 현재 문서에서 대상 문서까지의 상대 Markdown 경로로 계산한다. 같은 파일을 다른 폴더의 문서에 놓으면 ../가 포함될 수 있다.

Markdown 원문 보기에서 정확한 결과를 확인한다.

5.8초 영상은 Shelf에서 삽입 위치까지 문서를 옮기고, 전체 intent 메뉴에서 링크를 고른 뒤 저장된 상대 경로를 원문으로 확인한다.

링크를 선택할 때

• 독자가 원문으로 이동해 전체 맥락을 읽어야 한다.
• 현재 문서에는 짧은 출처나 참고 목록만 남기고 싶다.
• 원문이 바뀌어도 복사본을 다시 맞추는 작업을 만들고 싶지 않다.

링크 자체는 대상 내용을 복제하지 않는다. 대상 파일을 옮기거나 이름을 바꾸는 경우에는 Glif의 rename/reference rewrite 절차를 사용해 참조도 함께 갱신한다.

3. 참조 보기로 삽입한다

참조 보기는 Markdown carrier를 특수 문법으로 바꾸지 않는다. 일반 link를 삽입하고, 그 link를 계층도·마인드맵·칸반·표·차트·간트·페이지·계산로그·슬라이드 미리보기 중 어떤 방식으로 표현할지 Glif 설정에 저장한다.

예를 들어 칸반 참조 보기로 삽입을 선택해도 Markdown에는 정상적인 상대 link가 남는다. 따라서 Glif 표현 설정을 읽지 않는 다른 Markdown 도구에서도 최소한의 이동 경로는 유지된다.

참조 보기가 저장되지 않으면 Glif는 성공처럼 숨기지 않고 오류를 표시한다. 이때 Markdown link가 삽입되었는지 원문에서 확인하고, 표현 설정만 다시 저장한다.

4. 임베드로 삽입한다

embed-destination.md에 같은 원문을 드롭하고 임베드로 삽입을 선택한다.

현재 문서에는 다음 canonical wiki embed가 저장된다.

![[reusable-source.md]]

실시간 미리보기에서는 임베드 대상이 참조 chip으로 표시되고 열기, 옆으로 열기, 참조 복사 같은 동작을 제공한다.

5.8초 영상은 같은 문서를 다시 드래그하고 임베드 intent를 고른 뒤, 미리보기와 원문 문법을 차례로 확인한다.

임베드를 선택할 때

• 독자가 현재 문서를 떠나지 않고 원문 내용을 확인해야 한다.
• 원문을 한 곳에서 유지하고 여러 문서에서 재사용한다.
• 복제된 사본이 서로 달라지는 것을 피하고 싶다.

임베드는 복사가 아니다. 대상 파일을 읽을 수 없거나 경로가 깨지면 내용을 표시할 수 없으므로 Link Health와 대상 열기로 문제를 확인한다.

5. 본문으로 삽입한다

text-copy-destination.md에 같은 문서를 놓고 **본문으로 삽입 (중복 생성)**을 선택한다.

문서 전체나 heading section처럼 의미 있는 범위를 복사할 때는 확인 대화상자가 열린다.

대화상자는 다음 사실을 확인한다.

• 복사한 본문은 원문과 동기화되지 않는다.
• 어느 원문에서 가져오는지 표시한다.
• 문서 전체, heading section, 문단 중 어떤 범위를 복사하는지 표시한다.
• 큰 범위면 줄 수도 함께 표시한다.

확인을 누르면 원문의 main content를 삽입한다. 원문 front matter는 복사하지 않는다.

5.8초 영상은 본문 복사 intent를 고르고 확인한 뒤, 복제된 heading과 본문을 원문 보기에서 확인한다. 네이티브 확인 대화상자의 정확한 문구는 위 정지 이미지로 함께 제공한다.

본문 복사를 선택할 때

• 복사 뒤 목적 문서에 맞게 문장을 크게 고칠 계획이다.
• 원문의 이후 변경을 자동으로 따라가면 안 되는 스냅샷이 필요하다.
• 외부 배포물처럼 참조 해석기 없이도 완전한 본문이 필요하다.

단순히 같은 내용을 여러 곳에서 보여 주려는 목적이라면 임베드가 더 적합하다. 본문 복사는 중복 유지보수 비용을 의도적으로 받아들이는 작업이다.

문서·section·문단 payload의 차이

Shelf의 파일을 드래그하면 문서 전체 payload가 전달된다. Cart나 block 참조처럼 heading 또는 문단 식별자를 가진 payload를 놓으면 같은 intent가 더 좁은 범위에 적용된다.

본문 복사 범위를 계산할 수 없으면 Glif는 빈 내용이나 문서 전체를 추측해 삽입하지 않고 오류를 표시한다. 원문을 열어 heading·block anchor가 여전히 존재하는지 확인한 뒤 다시 시도한다.

삽입 위치와 줄 간격

Glif는 포인터가 가리킨 CodeMirror 위치에 결과를 삽입한다.

• 문장 중간에 놓으면 link나 embed도 그 위치에 들어간다.
• 본문 복사 앞뒤가 일반 문자이면 빈 줄을 보완해 블록 경계를 만든다.
• 현재 문서의 LF 또는 CRLF 줄바꿈 형식을 유지한다.
• 삽입 뒤 selection은 새 내용의 끝으로 이동한다.
• 하나의 editor transaction으로 들어가므로 즉시 실행 취소할 수 있다.

의도하지 않은 위치에 들어갔다면 저장 전에 Ctrl+Z로 되돌리고, 빈 줄이나 명확한 문단 경계에 다시 놓는다.

원문과 목적 문서에 생기는 변화

이 실증에서는 세 작업을 마친 뒤 reusable-source.md를 처음 byte와 비교해 동일함을 확인했다.

저장과 재열기 확인

1. 삽입 뒤 상단 저장 상태가 저장됨이 될 때까지 기다린다.
2. Markdown 원문 보기에서 link, embed 또는 복사된 본문을 확인한다.
3. 다른 문서를 열었다가 목적 문서로 돌아온다.
4. link와 embed가 같은 대상을 가리키는지, 복사한 본문이 그대로 남아 있는지 확인한다.
5. 더 강한 검증이 필요하면 Glif를 닫고 같은 Scope를 다시 연다.

화면에만 보이고 파일에 저장되지 않은 상태와 실제 Markdown mutation을 구분하려면 반드시 원문과 재열기를 함께 확인한다.

오류와 복구

문서를 놓아도 메뉴가 열리지 않는다

• Markdown 파일이 아니라 폴더를 드래그하지 않았는지 확인한다.
• 현재 Binder 밖의 물리 경로라면 먼저 Scope에 추가하거나 workspace mount로 연결한다.
• 목적 문서가 편집 가능한 상태인지 확인한다.
• Shelf가 갱신되지 않았다면 폴더를 새로 고침하고 다시 시도한다.

현재 문서 경로를 계산할 수 없다고 나온다

목적 문서가 아직 저장되지 않았거나 Binder·workspace 기준 경로가 불명확할 수 있다. 문서를 Scope 안에 저장하고 다시 연 뒤 드롭한다.

임베드가 비어 있거나 대상을 열 수 없다

원본 파일의 이동·rename으로 경로가 오래되었는지 확인한다. Link Health에서 깨진 참조를 찾고, 필요하면 기존 embed를 지운 뒤 현재 Shelf 문서를 다시 드롭한다.

본문 복사 확인을 취소했다

취소는 정상적인 무변경 결과다. 목적 문서에 아무 내용도 삽입하지 않는다. 원본과 계속 연결하려던 것이라면 다시 드롭해 링크나 임베드를 선택한다.

참조 보기는 삽입됐지만 설정 저장 오류가 보인다

Markdown 원문에 일반 link가 남았는지 확인한다. link가 있으면 이동 가능한 최소 결과는 보존된 것이다. 쓰기 가능한 Scope인지 확인한 뒤 같은 link의 참조 보기 설정을 다시 선택한다.

키보드와 접근성 경계

현재 문서 드롭 시작은 pointer drag를 전제로 한다. 드롭 메뉴 자체는 Esc로 취소할 수 있고 각 항목은 menu item으로 노출된다. pointer를 사용하기 어려우면 다음 우회가 가능하다.

• 일반 link는 link 복사·붙여넣기 또는 Markdown 직접 입력
• embed는 현재 문서·section·문단 embed 복사 명령 후 붙여넣기
• 독립 사본은 필요한 범위를 복사하되 출처와 동기화되지 않는다는 점을 직접 기록

문서 드롭과 완전히 같은 keyboard-only 시작 경로가 필요한 경우에는 별도 접근성 개선 대상으로 추적한다. 가이드에서는 존재하지 않는 단축키를 있는 것처럼 설명하지 않는다.

완료 체크리스트

• Shelf 문서를 목적 문서의 명확한 삽입 위치에 놓았다.
• 드롭 직후 자동 삽입되지 않고 intent 메뉴가 열렸다.
• 링크 결과가 상대 Markdown link로 저장됐다.
• 임베드 결과가 canonical wiki embed로 저장됐다.
• 본문 복사 전에 비동기화 경고를 확인했다.
• 본문 복사에서 원본 front matter가 제외됐다.
• 세 작업 뒤에도 원본 문서가 변경되지 않았다.
• 저장됨과 문서 재열기를 확인했다.

다음으로 요약·슬라이드 메타데이터와 프로젝션 설정을 함께 읽으면 문서 내용, 재사용 metadata, 다른 문서를 참조하는 표현 상태가 각각 어디에 저장되는지 연결해서 이해할 수 있다.