Notion ZIP import로 강의 문서/이미지 생성 및 네비 반영

[jalju0804]

📦 노션 ZIP 임포트 워크플로우 추가

개요

노션에서 export한 ZIP 파일을 Quarto 강의 문서로 자동 변환하는 에이전트 워크플로우를 추가합니다.

---

변경 사항

추가된 파일 및 디렉토리

경로	설명
tools/scripts/import_notion_zip.py	노션 ZIP → Quarto .qmd 변환 스크립트
tools/scripts/README.md	3단계 워크플로우 및 I/O 규칙 문서
tools/imports/ch{N}/	챕터별 ZIP 파일 임시 저장 디렉토리
tools/imports/ch{N}/processed/	처리 완료된 ZIP 이동 경로

자동화 작업 (에이전트 실행 시)

에이전트에게 "tools/scripts/readme.md를 읽고 진행해줘" 라고 요청하면 아래 작업이 순서대로 실행됩니다.

1. 사용법 파악 — tools/scripts/README.md에서 워크플로우 및 I/O 규칙 확인

2. ZIP 확인 — imports/ch{N}/에서 노션 export ZIP 파일 탐색

3. 드라이런 — 예상 산출물 미리 점검

   python3 import_notion_zip.py "../imports/ch6/<ZIP이름>.zip" \
     ch6 ovs_vxlan_vpn --title "OVS/VXLAN 가상 네트워크 만들기" --dry-run

4. 실제 변환 실행

   • 강의 문서 생성: lectures/ch{N}/<slug>.qmd
   • 이미지 복사: lectures/ch{N}/images/<slug>/
   • 네비게이션 업데이트: _quarto.yml, lectures/index.qmd
   • ZIP 정리: imports/ch{N}/processed/로 이동

5. 검증 — 생성된 문서·이미지 존재 여부 및 내비게이션 반영 확인

---

사용 방법

tools/imports/ch6/
└── OVS_VXLAN 가상 네트워크 만들기.zip   ← 노션에서 export한 ZIP

해당 챕터 폴더에 ZIP 파일을 위치시킨 뒤, 아래 두 가지 방법 중 하나로 진행합니다.

---

방법 A — 에이전트 사용 (권장)

에이전트에게 아래와 같이 요청합니다.

tools/scripts/readme.md를 읽고 진행해줘

에이전트가 README를 읽고 드라이런 → 변환 → 검증까지 자동으로 처리합니다.

---

방법 B — 직접 스크립트 실행

에이전트 없이 터미널에서 직접 실행할 수도 있습니다.

1단계: 드라이런으로 산출물 미리 확인

cd tools/scripts
python3 import_notion_zip.py \
  "../imports/ch6/OVS_VXLAN 가상 네트워크 만들기.zip" \
  ch6 ovs_vxlan_vpn \
  --title "OVS/VXLAN 가상 네트워크 만들기" \
  --dry-run

출력 결과로 생성될 파일 목록과 경로를 확인합니다. 문제가 없으면 다음 단계로 진행합니다.

2단계: 실제 변환 실행

--dry-run 옵션을 제거하고 실행합니다.

cd tools/scripts
python3 import_notion_zip.py \
  "../imports/ch6/OVS_VXLAN 가상 네트워크 만들기.zip" \
  ch6 ovs_vxlan_vpn \
  --title "OVS/VXLAN 가상 네트워크 만들기"

3단계: 결과 확인

# 문서 생성 확인
ls lectures/ch6/ovs_vxlan_vpn.qmd

# 이미지 복사 확인
ls lectures/ch6/images/ovs_vxlan_vpn/

# 네비게이션 반영 확인
grep "ovs_vxlan_vpn" _quarto.yml
grep "ovs_vxlan_vpn" lectures/index.qmd

# ZIP 정리 확인
ls tools/imports/ch6/processed/

인자 설명

인자	설명	예시
<ZIP 경로>	노션 export ZIP 파일 경로	"../imports/ch6/파일명.zip"
<챕터>	대상 챕터 식별자	ch6
<슬러그>	문서 파일명으로 사용할 슬러그 (소문자·언더스코어)	ovs_vxlan_vpn
--title	문서 제목	"OVS/VXLAN 가상 네트워크 만들기"
--dry-run	실제 파일을 생성하지 않고 예상 결과만 출력	(플래그)

---

⚠️ 주의 사항

ZIP 파일은 Git에서 제외됩니다

tools/imports/ 하위의 ZIP 파일은 .gitignore에 의해 추적되지 않습니다.
로컬에서만 보관되며, 원격 저장소에는 올라가지 않습니다.

챕터 소개 문서의 하위 목차는 수동으로 추가해야 합니다

lectures/ch{N}_lec.qmd 와 같은 챕터 소개 문서에 ## 하위 목차 섹션이 있는 경우,
에이전트가 자동으로 항목을 삽입하지 않습니다.

에이전트 작업 완료 후, 해당 섹션을 직접 검토하여 새로 추가된 문서 링크를 수동으로 넣어주세요.

---

테스트

• 드라이런으로 산출물 경로 사전 확인
• lectures/ch6/ovs_vxlan_vpn.qmd 생성 확인
• lectures/ch6/images/ovs_vxlan_vpn/ 이미지 복사 확인
• _quarto.yml 및 lectures/index.qmd 네비게이션 반영 확인
• 처리된 ZIP이 processed/로 이동됨 확인