Outline으로 긴 문서 구조 편집하기

Outline은 현재 Markdown의 heading을 읽어 문서 구조를 tree로 보여 준다. 별도 목차 데이터베이스가 아니며, heading을 선택하면 원문 위치로 이동하고 section 이동·복제·drag reorder를 실행하면 heading과 그 하위 본문이 Markdown 안에서 함께 이동한다.

이 장에서는 구조를 보는 동작과 원문을 바꾸는 동작을 분리해 익힌다.

동작	Markdown 변경	유지 범위
Outline 열기·heading 선택·현재 위치 reveal	없음	현재 문서와 editor selection
표시 heading 레벨 변경	없음	현재 문서의 Outline 표시 상태
위로·아래로 이동	있음	같은 parent의 인접 section 순서
복제	있음	선택 heading과 전체 하위 본문
drag reorder	있음	선택 section subtree의 원문 순서
현재 section focus	없음	현재 editor 세션
다른 section 접기	없음	현재 editor 세션의 fold 상태

ℹ️

화면 아래 안내 문구와 파란 원은 캡처 설명이다. Markdown 원문에는 저장되지 않는다. 실습은 예제 파일 복사본에서 진행하면 원본 fixture를 언제든 다시 사용할 수 있다.

실습 문서

릴리즈 운영 매뉴얼 outline-lab.md는 H1 하나, H2 다섯 개와 H3~H6 중첩 heading을 가진다.

릴리즈 운영 매뉴얼
├─ 목적
│  └─ 독자
│     └─ 전제 조건
│        └─ 제한 사항
│           └─ 예외 기록
├─ 준비
│  ├─ 변경 범위
│  └─ 준비 체크
├─ 실행
│  ├─ 빌드
│  └─ 게시
├─ 검증
│  ├─ 기능 확인
│  └─ 문서 확인
└─ 복구
   ├─ 중단 조건
   └─ 복구 기록

파일을 별도 폴더에 복사한 뒤 그 폴더를 Scope로 연다. 이동·복제·drag 단계는 복사본을 실제로 수정한다.

1. Outline을 연다

outline-lab.md를 연다.
Ctrl+P를 누른다.
목차 또는 Outline을 검색한다.
Outline panel을 연다.
오른쪽 panel의 제목이 릴리즈 운영 매뉴얼이고 그 아래에 목적, 준비, 실행, 검증, 복구가 있는지 확인한다.

Outline이 비어 있다면 현재 활성 문서에 Markdown heading이 있는지 먼저 확인한다. 굵은 문장이나 큰 글자처럼 보이는 일반 텍스트는 # heading이 아니므로 tree 항목이 되지 않는다.

2. H2~H6 전체 구조를 읽는다

Outline 상단의 H2~H6 버튼은 tree에서 펼쳐 볼 최대 깊이를 정한다. H6을 선택하면 fixture의 전체 중첩 구조가 보인다.

H2부터 H6까지 펼친 릴리즈 운영 매뉴얼 Outline tree

들여쓰기는 heading 계층을 뜻한다. 예를 들어 예외 기록은 제한 사항 아래에 있고, 그 상위에는 전제 조건, 독자, 목적이 있다. Outline의 순서와 깊이가 예상과 다르면 Source에서 다음을 확인한다.

heading marker의 # 개수
상위 heading 없이 H4나 H5부터 시작하지 않았는지
코드 fence 안의 #를 heading으로 오해하지 않았는지
같은 이름의 heading이 여러 개라면 각각의 주변 section이 올바른지

3. 표시 깊이를 줄인다

긴 문서에서 상위 section만 훑으려면 H2를 선택한다.

H2 표시 깊이로 상위 section만 남기고 하위 heading을 접은 Outline

이 동작은 원문의 ###, #### 같은 marker를 바꾸거나 내용을 삭제하지 않는다. 표시 깊이를 다시 H6으로 바꾸면 같은 하위 heading이 돌아온다.

선택	적합한 상황
H2	장 단위 순서와 큰 흐름 점검
H3	장 안의 주요 절차까지 검토
H4~H5	세부 조건과 하위 작업 탐색
H6	전체 heading 계층 감사

버튼이 비활성화되어 있다면 현재 문서에 그 레벨의 heading이 없다는 뜻이다.

4. Outline에서 원문으로 이동한다

표시 깊이를 H6으로 바꾼다.
검증 아래의 문서 확인을 선택한다.
editor가 ### 문서 확인 위치로 이동하는지 확인한다.

Outline에서 문서 확인 heading을 선택해 원문 section으로 이동한 화면

선택은 heading 제목 한 줄만 찾는 검색과 다르다. 현재 heading identity를 기준으로 editor selection과 scroll 위치를 함께 이동한다. 동명 heading이 있으면 tree 계층과 원문 문맥을 함께 확인한다.

5. 현재 편집 위치를 Outline에서 찾는다

반대 방향도 동작한다. editor에서 cursor를 문서 마지막의 복구 기록 section으로 옮기면 Outline이 해당 경로를 펼치고 항목을 선택한다.

현재 editor 위치에 맞춰 복구 기록 heading을 선택해 보여 주는 Outline

긴 원문을 scroll하다 현재 장을 잃었을 때 유용하다. 현재 위치가 일반 본문 line이면 가장 가까운 상위 heading이 선택된다. heading이 전혀 없는 문서에서는 reveal할 구조가 없다.

6. section 메뉴를 연다

Outline 항목을 마우스 오른쪽 버튼으로 선택하면 구조 작업 메뉴가 열린다.

메뉴	결과
위로 이동	같은 parent의 이전 sibling 앞으로 section 이동
아래로 이동	같은 parent의 다음 sibling 뒤로 section 이동
복제	section subtree를 바로 다음 위치에 복사
섹션 링크 복사	현재 heading을 가리키는 link 복사
Cart에 담기	문서 전체가 아니라 heading section을 Cart에 추가
섹션을 글로 분리	section을 새 Markdown 문서로 추출
현재 섹션 집중	선택 section을 강조하고 나머지를 흐리게 표시
다른 섹션 접기	선택 section 이외의 본문을 editor에서 접기

이 장에서는 ED-02~10에 해당하는 이동·복제·focus·접기를 다룬다. 링크·Cart·분리는 뒤의 추출과 조립 장에서 자세히 설명한다.

7. section을 위·아래로 이동한다

준비에서 아래로 이동을 실행하면 같은 H2 parent 아래의 다음 sibling인 실행 뒤로 이동한다.

 ## 목적
-## 준비
 ## 실행
+## 준비
 ## 검증
 ## 복구

준비 section이 실행 뒤로 이동하고 editor selection과 Outline 순서가 함께 갱신된 화면

heading만 움직이는 것이 아니다. 준비 아래의 설명, 변경 범위, 준비 체크와 각 본문이 한 section subtree로 함께 이동한다. 첫 sibling에서 위로 이동, 마지막 sibling에서 아래로 이동처럼 갈 곳이 없는 명령은 원문을 바꾸지 않는다.

이동 뒤에는 다음을 확인한다.

Outline의 sibling 순서가 의도와 같은가?
Source에서 heading과 하위 본문이 끊기지 않았는가?
한 단계 undo로 원래 순서가 복구되는가?

8. section 전체를 복제한다

실행에서 복제를 선택하면 ## 실행부터 다음 같은 레벨 heading 직전까지를 바로 다음 위치에 복사한다.

## 실행

검증된 결과물을 순서대로 생성하고 게시한다.

### 빌드

제품과 가이드의 release candidate를 생성한다.

### 게시

승인된 output만 대상 환경에 게시한다.

실행 heading과 빌드·게시 하위 section 전체가 바로 다음 위치에 복제된 화면

복제 직후에는 같은 제목의 section이 두 개가 된다. 초안을 변형하려는 목적이라면 새 복사본의 heading을 먼저 고쳐 동명 anchor와 링크 문맥의 혼란을 줄인다. 복제는 새 파일을 만드는 기능이 아니며 현재 Markdown 안에서만 일어난다.

9. 현재 section에 집중한다

검증에서 현재 섹션 집중을 선택하면 검증 subtree는 선명하게 남고 나머지 section은 흐려진다.

검증 section만 강조하고 다른 section을 흐리게 표시한 focus 상태

focus는 원문을 자르거나 별도 문서로 분리하지 않는다. 같은 메뉴를 다시 실행하면 focus를 해제한다. 저장·publish 결과에는 focus 상태가 내용으로 들어가지 않는다.

다음 상황에서 유용하다.

긴 문서의 한 장만 집중해서 교정할 때
비슷한 heading 사이에서 현재 수정 범위를 시각적으로 고정할 때
screen sharing 중 검토 대상을 분명히 할 때

10. 선택한 section 외의 본문을 접는다

검증에서 다른 섹션 접기를 선택하면 다른 section의 본문이 접힘 표시로 줄어든다.

검증 section은 펼치고 목적, 실행, 준비와 복구 본문을 접은 editor

접힘 표시의 생략 기호는 삭제된 텍스트가 아니다. 다시 펼치거나 문서를 재열어 내용을 확인할 수 있다. fold 상태에서 복사하거나 구조를 판단할 때는 보이지 않는 하위 본문이 존재할 수 있음을 기억한다.

focus와 fold의 차이는 다음과 같다.

동작	다른 section	현재 section	원문
focus	보이지만 흐리게 표시	강조	변경 없음
다른 section 접기	heading과 접힘 표시만 남김	펼침	변경 없음

11. drag로 section 순서를 바꾼다

여러 section을 멀리 옮길 때는 Outline 항목을 원하는 sibling 위치로 drag한다. 다음 화면은 앞 단계의 연속 상태에서 복구를 준비 앞으로 옮기는 예다.

복구 section을 이동하기 전 H2 Outline 순서

복구 section을 준비 앞으로 drag해 Outline과 Markdown 순서를 함께 바꾼 화면

drag도 preview 전용 정렬이 아니다. drop이 성공하면 Markdown section 순서가 실제로 바뀌고 문서가 수정 상태가 된다. 안전하게 사용하려면 다음 원칙을 따른다.

먼저 H2나 H3처럼 필요한 깊이만 표시해 drop 위치를 명확히 한다.
가능하면 같은 parent의 sibling 사이에서 이동한다.
parent를 자기 자신이나 자기 descendant 아래로 넣는 순환 구조는 허용되지 않는다.
drop 직후 Outline뿐 아니라 Source의 heading marker와 subtree 범위를 확인한다.
원하지 않은 결과는 추가 drag보다 먼저 한 단계 undo한다.

이번 실증에서 H2 순서는 다음처럼 변했다.

 목적
 실행
 실행
+복구
 준비
 검증
-복구

실행이 두 개인 것은 앞 단계에서 복제를 실행한 연속 실습 결과다.

전체 조작 영상

heading 깊이와 현재 위치 reveal

다음 6.5초 영상은 H6 전체 tree에서 H2 상위 구조로 줄이고, 다시 H6으로 펼쳐 문서 확인 원문을 연 뒤 editor 끝으로 이동해 복구 기록이 Outline에서 선택되는 흐름을 보여 준다.

이동·복제·focus·접기

다음 5.8초 영상은 준비를 아래로 이동하고, 실행을 복제하고, 검증에 focus를 적용한 뒤 다른 section을 접는 연속 작업을 보여 준다.

drag reorder

다음 3.8초 영상은 마지막 복구 H2 section을 준비 앞으로 drag하고, Outline과 원문이 함께 갱신되는 순간을 보여 준다.

예상과 다를 때

증상	먼저 확인할 것	조치
Outline이 비어 있다	현재 문서와 `#` heading 존재 여부	`outline-lab.md`를 다시 열고 Source의 heading marker를 확인한다
H4~H6 버튼이 비활성이다	해당 레벨 heading 존재 여부	fixture 원본인지 확인하고 임의로 marker를 바꾸지 않았는지 점검한다
하위 heading이 보이지 않는다	표시 깊이와 parent 펼침 상태	더 깊은 레벨을 선택하고 parent 화살표를 펼친다
heading 선택 뒤 다른 위치가 열린다	동명 heading과 현재 문서	tree 계층을 확인하고 현재 활성 tab이 맞는지 점검한다
위·아래 이동이 아무 변화가 없다	첫·마지막 sibling 여부	같은 parent에서 이동 가능한 인접 sibling이 있는 항목을 선택한다
복제 뒤 내용 일부가 없는 것처럼 보인다	fold 상태와 subtree 경계	다른 section을 펼치고 Source에서 다음 같은 레벨 heading까지 확인한다
focus가 publish에도 남을까 걱정된다	원문 변경 indicator	focus는 세션 표현이므로 Source diff가 없는지 확인한다
drag가 시작되지 않는다	항목 위치와 진행 중인 reorder	tree 항목 본체에서 다시 시작하고 이전 갱신이 끝날 때까지 기다린다
drag 결과가 의도와 다르다	drop parent와 heading marker	즉시 undo하고 같은 parent sibling 사이에서 다시 수행한다

완료 확인

Outline이 Markdown heading에서 파생된다는 점을 설명할 수 있다.
H2와 H6 표시 깊이를 오가며 원문이 바뀌지 않음을 확인했다.
Outline heading을 눌러 정확한 원문 section으로 이동했다.
editor 위치를 바꾸고 Outline의 현재 heading reveal을 확인했다.
위·아래 이동이 heading과 하위 본문 전체를 옮기는지 확인했다.
section을 복제하고 같은 제목의 새 복사본을 확인했다.
focus와 fold가 원문을 바꾸지 않는 세션 동작임을 확인했다.
H2 section을 drag하고 Source 순서가 실제로 변경됐는지 확인했다.
각 원문 변경을 한 단계 undo로 복구할 수 있는지 확인했다.