문단과 섹션을 새 노트로 추출하고 링크를 임베드로 바꾸기
문서가 길어지면 한 파일 안에서 계속 정리하는 것보다, 독립적으로 이름 붙이고 연결할 수 있는 note로 분리하는 편이 낫다. Glif의 노트 추출은 선택한 문단이나 heading section을 새 Markdown 파일로 만들고 원래 위치에 상대 link를 남긴다. 이미 존재하는 내부 Markdown link는 현재 링크를 임베드로 전환하여 같은 문맥에서 대상 identity와 바로가기 action을 볼 수 있다.
이 장에서 다루는 세 기능은 모두 Markdown 원문을 바꾼다.
| 기능 | 입력 | 새 파일 | 원문 결과 |
|---|---|---|---|
| 현재 문단을 새 노트로 추출 | cursor가 있는 일반 문단 | 생성 | 문단 전체를 새 note 상대 link로 교체 |
| 현재 섹션을 새 노트로 추출 | cursor가 있는 heading section | 생성 | heading은 유지하고 section 본문을 새 note 상대 link로 교체 |
| 현재 링크를 임베드로 전환 | cursor 아래 내부 Markdown link | 없음 | [label](path.md)를 ![[path.md]]로 교체 |
언제 추출하고 언제 그대로 둘까
다음 조건 중 두 가지 이상에 해당하면 추출을 고려한다.
- 다른 문서에서도 같은 내용을 재사용한다.
- 고유한 제목, tag, link와 변경 이력이 필요하다.
- 한 section이 현재 문서의 주제보다 훨씬 길어졌다.
- 해당 내용을 여러 문서가 참조해야 한다.
- 별도 담당자나 독립적인 완료 조건이 있다.
반대로 문맥 없이는 의미가 없거나 한두 문장에 불과하고 다시 참조할 가능성이 낮다면 현재 문서에 두는 편이 낫다. 지나친 분리는 짧은 note와 link만 늘려 읽기 흐름을 끊을 수 있다.
실습 파일
아래 네 파일은 한 폴더에 함께 둔다.
- 문단 추출 실습
paragraph-extract-lab.md - 섹션 추출 실습
section-extract-lab.md - 링크→임베드 실습
link-to-embed-lab.md - 임베드 대상
reference-target.md
폴더를 별도 위치에 복사하고 그 복사본을 Scope로 연다. 실증 캡처도 매 시도마다 새 임시 복사본을 만들어 공개 fixture 자체는 수정하지 않았다.
1. 현재 문단을 새 노트로 추출한다
paragraph-extract-lab.md를 열고 승인된 배포 창은…으로 시작하는 문단 위에서 마우스 오른쪽 버튼을 누른다. 현재 문단을 새 노트로 추출을 선택한다.
heading, 목록, 표, 코드 fence가 아니라 하나의 일반 문단 안에서 실행해야 한다. 문단 앞이나 뒤의 빈 줄은 경계를 구분하지만 새 note의 핵심 본문으로 복사되지 않는다.
1.1 추출 내용을 검토한다
dialog에서 다음 값을 확인한다.
| 필드 | 실습 값 | 역할 |
|---|---|---|
| 제목 | 배포 창 운영 절차 |
새 note의 title과 원문 link label |
| 파일 이름 | deployment-window.md |
새 Markdown 파일 이름 |
| 저장 위치 | 비움 | 현재 Scope root에 저장 |
| 추출 미리보기 | 승인된 배포 창 문단 | 실제로 이동할 Markdown 범위 |
자동 제안은 시작점이다. 제목은 사람이 읽기 좋은 의미 단위로 다듬고, 파일 이름은 다른 환경에서도 안정적인 짧은 이름을 사용한다. 파일 이름에서 .md를 생략하면 Glif가 붙인다.
저장 위치에는 Scope root 기준 상대 경로만 입력한다. 예를 들어 concepts/core는 허용되지만 드라이브 문자, /로 시작하는 절대 경로, ..을 포함한 상위 경로는 허용되지 않는다.
1.2 새 note를 확인한다
추출을 누르면 Glif가 새 파일을 만들고 해당 note를 연다.
실증 결과 새 note는 다음 의미를 보존했다.
---
title: 배포 창 운영 절차
---
승인된 배포 창은 매주 화요일 14시다. 담당자는 배포 30분 전에 상태 페이지와 롤백 패키지를 확인하고, 변경 요약을 운영 채널에 공유한다.정확한 front matter 직렬화에는 Glif가 관리하는 기본 metadata가 더 포함될 수 있다. 검증할 핵심은 입력한 title과 추출된 Markdown 본문이 새 파일에 있다는 점이다.
1.3 원문 link를 확인한다
원래 paragraph-extract-lab.md로 돌아오면 추출된 문단 위치가 다음 상대 link로 바뀌어 있다.
[배포 창 운영 절차](deployment-window.md)
뒤의 설명과 후속 작업 section은 그대로 남는다. 즉 문서 전체를 재작성하는 것이 아니라 해결된 문단 범위만 치환한다.
문단 추출 영상
다음 5.6초 영상은 문단 menu를 열고, dialog에서 제목·파일 이름·미리보기를 확인하고, 새 note와 원문 상대 link를 차례로 검증한다.
2. heading section 전체를 새 노트로 추출한다
section 추출은 현재 heading 아래의 본문과 더 깊은 하위 heading을 하나의 범위로 다룬다. section-extract-lab.md의 장애 대응 원칙 heading에서 마우스 오른쪽 버튼을 누르고 현재 섹션을 새 노트로 추출을 선택한다.
이 예제에서 추출 범위는 다음과 같다.
장애 대응 원칙의 첫 문단
├─ 초기 대응
│ └─ 순서 목록 3개
└─ 종료 조건
└─ 확인 목록 3개다음 같은 레벨의 ## 정기 점검은 범위에 포함되지 않는다.
2.1 section 미리보기를 검토한다
제목을 장애 대응 원칙, 파일 이름을 incident-response-principles.md로 둔다. 미리보기에 초기 대응, 종료 조건과 그 목록이 함께 보이는지 확인한다.
미리보기에서 예상보다 적거나 많은 내용이 보인다면 추출하기 전에 취소하고 원문의 heading 레벨을 확인한다. section 끝은 다음 같거나 더 얕은 heading에서 결정되므로 잘못된 # 깊이는 추출 범위에도 영향을 준다.
2.2 새 note의 하위 구조를 확인한다
추출된 note에는 기존 H3 heading과 목록이 그대로 남는다.
새 note 자체의 document title은 장애 대응 원칙이다. 추출한 원래 H2 marker는 새 note 본문에 중복으로 넣지 않고, 그 아래의 본문과 하위 구조를 이동한다.
2.3 원문 heading과 link를 확인한다
원문에서는 ## 장애 대응 원칙 heading을 유지하고 그 본문을 새 note link로 바꾼다.
## 장애 대응 원칙
[장애 대응 원칙](incident-response-principles.md)
## 정기 점검
heading을 유지하므로 원래 문서의 큰 목차와 읽기 순서는 바뀌지 않는다. 다만 기존 heading을 직접 가리키던 block/heading reference가 있다면 추출 뒤에도 그 reference가 기대한 의미를 유지하는지 Link Health와 실제 열기로 확인한다.
section 추출 영상
다음 5.6초 영상은 heading menu, 전체 section 미리보기, 새 note의 하위 구조와 원문 heading 아래 link를 순서대로 보여 준다.
3. 내부 Markdown link를 wiki embed로 전환한다
link와 embed는 연결 대상이 같아도 읽는 방식이 다르다.
| 표현 | 적합한 목적 | Markdown |
|---|---|---|
| link | 필요할 때 대상 문서를 연다 | [배포 점검표](reference-target.md) |
| embed | 현재 문맥에서 대상 identity와 관련 action을 바로 확인한다 | ![[reference-target.md]] |
link-to-embed-lab.md에는 reference-target.md를 가리키는 일반 Markdown link가 있다.
link label 위에서 마우스 오른쪽 버튼을 누르고 현재 링크를 임베드로 전환을 선택한다. 같은 line의 일반 텍스트 위가 아니라 실제 link 범위 안에서 menu를 열어야 한다.
3.1 원문 변환을 확인한다
cursor를 변환된 범위 안에 두면 canonical wiki embed 문법을 확인할 수 있다.
-[배포 점검표](reference-target.md)
+![[reference-target.md]]
변환은 대상 파일을 복사하지 않는다. 현재 문서의 link 표현만 바뀌며 target인 reference-target.md는 그대로 유지된다. 외부 URL, mailto:, tel:처럼 내부 Markdown 문서로 해결할 수 없는 link는 이 명령의 대상이 아니다.
3.2 inline embed 표현을 확인한다
cursor를 다른 위치로 옮기면 Glif가 embed를 읽기 가능한 inline 표현으로 바꾼다. 이번 실증에서는 대상 제목 배포 점검표, 상대 경로 reference-target.md와 대상 편집, 열기, 옆으로 열기, 참조 복사 action이 표시됐다.
이 inline 표현은 Markdown에 별도 HTML이나 UI 상태를 저장한 결과가 아니다. 원문의 ![[reference-target.md]]에서 파생된다. target이 이동·삭제되면 원문 경로가 해결되는지 다시 확인해야 한다.
link→embed 변환 영상
다음 5.1초 영상은 일반 link에서 menu를 열고, canonical wiki embed 원문을 확인한 뒤 inline target action 표현으로 돌아오는 흐름을 보여 준다.
추출의 저장 안전성
성공으로 보이려면 다음 두 결과가 모두 있어야 한다.
- 지정한 경로에 새 Markdown note가 존재한다.
- 원래 문서가 새 note를 가리키는 상대 link로 저장됐다.
Glif는 새 note 생성이나 원문 저장 중 오류가 발생하면 완료 toast로 숨기지 않고 작업을 실패 처리한다. 오류 뒤에는 다음을 확인한다.
- 새 파일만 남고 원문이 바뀌지 않은 반쪽 상태가 없는가?
- 원문이 link로 바뀌었는데 target 파일이 없는가?
- 같은 이름의 기존 파일을 덮어쓰지 않았는가?
- 저장 위치가 Scope 밖으로 벗어나지 않았는가?
성공한 추출을 되돌릴 때는 원문 link만 지우면 새 note가 남는다. 반대로 새 note만 삭제하면 깨진 link가 남는다. 원래 구조로 완전히 합치려면 새 note 본문을 원문 위치로 되돌리고 link를 제거한 뒤, 참조자가 없는지 확인하고 새 note를 삭제한다.
예상과 다를 때
| 증상 | 원인 후보 | 조치 |
|---|---|---|
| 문단 추출 menu를 실행했지만 대상이 없다고 나옴 | cursor가 heading, 목록, 표, fence 또는 빈 줄에 있음 | 추출할 일반 문단 안에서 다시 우클릭 |
| section 추출 범위가 너무 큼 | 다음 sibling heading의 레벨이 더 깊음 | Source에서 heading marker 깊이를 고친 뒤 미리보기 재확인 |
| section 추출 범위가 너무 작음 | 본문 일부가 같은 레벨 heading으로 분리됨 | 의도한 계층으로 heading을 조정하거나 여러 section을 각각 추출 |
| 같은 이름의 문서가 이미 있다고 나옴 | target 파일 충돌 | 기존 note를 재사용할지 검토하고 고유 파일 이름 선택 |
| 저장 위치 오류 | 절대 경로 또는 .. 사용 |
Scope root 기준의 정상 상대 경로 입력 |
| link→embed가 변환되지 않음 | cursor가 link 범위 밖이거나 외부 URL임 | 내부 .md link label 또는 destination 위에서 다시 실행 |
| embed에 target을 찾을 수 없음 | 상대 경로 오타, rename 또는 삭제 | target 존재 여부와 현재 문서 기준 상대 경로 확인 |
| 변환 뒤 label이 사라짐 | canonical embed는 target path를 기준으로 생성 | 필요하면 target title을 정리하고 inline 표현에서 확인 |
완료 체크리스트
- 추출 미리보기가 의도한 문단 또는 section 전체와 일치한다.
- 제목, 파일 이름과 Scope root 기준 저장 위치를 확인했다.
- 새 note에 title과 추출 본문이 보존됐다.
- 원문에 새 note의 상대 Markdown link가 남았다.
- section 추출에서는 원래 heading과 다음 sibling section이 유지됐다.
- link→embed 뒤 원문이 canonical
![[...]]문법이다. - inline embed에서 target 제목·경로와 action을 확인했다.
- Link Health에서 새 깨진 참조가 생기지 않았다.
다음 단계에서는 note 이름을 바꿀 때 alias와 explicit reference가 함께 어떻게 갱신되는지 다룬다.