notion-ml

Notion Markup Language (NML) — 마크다운과 노션 블록 사이의 중간 언어.

소스는 마크다운이다. 노션에만 있는 구조만 <!--@ … --> 지시자로 덧댄다. 편집기에서는 평범한 파일로 읽히고, 필요할 때 블록 단위로 노션에 반영한다.

로컬이 정본이고, 노션은 반영 대상이다. 반영은 세 단계다: 비교(diff) → 선택(add) → 적용(push).

30초 요약

# 설치
uv tool install "git+https://github.com/devcomfort/notion-ml#subdirectory=packages/notionml"

# 노트 저장소 지정
export NOTIONML_STORE="$HOME/notes"

# 원격과 비교 → 고르기 → 반영
nl diff notes/topic/3장_08.md
nl add  notes/topic/3장_08.md#1,3
nl push --apply

왜 필요한가

문제	notion-ml의 답
마크다운으로 노션을 쓰면 표·토글·수식이 깨진다	노션 구조만 지시자로 표현하고, 나머지는 그대로 마크다운
노션에서 누가 고치면 로컬과 갈라진다	블록 단위 3자 비교로 «로컬 변경»과 «원격 변경»을 구분
자동 반영이 문서를 망칠 수 있다	모르면 멈춘다. 댓글 앵커·종류 불일치·표 열 변경은 쓰지 않는다
되돌릴 수단이 없다	쓰기 전 스냅숏, 쓴 뒤 재조회 검증, 저널(WAL) 기록

안전 모델

• 차단 조건: 원격과 블록 종류 불일치, 표 열 수 변경, 소스 타입 오류, 로컬 재정렬 → 아무것도 쓰지 않음(종료 3).
• 댓글 달린 블록은 고치지 않는다(앵커 보호).
• 모호하면 사람이 결정: pull(원격 승) / keep(로컬 승) / rebase(원격 먼저 얹기).

문서

문서	내용
설치	uv·pipx·pip 설치, 토큰, 저장소 지정
명령	아홉 명령의 정확한 동작과 종료 코드
언어	지시자·블록 모델·표·그림 규칙
동작 원리	변경 감지, 콘텐츠 비교, 저장 구조
로드맵	다음 단계와 하지 않는 것