Notation은 무료인가

무료다. GPL-3.0 오픈소스이고 유료 요금제가 없다. 비용은 Notion 워크스페이스뿐이며, 개인 용도라면 Notion 무료 요금제로 충분하다.

Notion 계정이 필요한가

필요하다. Notation은 공식 Notion API로 쓰기 때문에 워크스페이스와 상위 페이지, 그 페이지에 접근 권한이 있는 내부 인티그레이션이 있어야 한다. 시크릿은 ~/.notation/Notation.toml 에 넣는다.

어떤 Markdown 문법을 지원하나

제목, 문단, 코드 블록, 순서 있는 목록과 없는 목록, 표, 링크, 이미지를 지원한다. 같은 폴더 안 페이지끼리의 상대 링크는 Notion 페이지 링크로 바뀐다. 로컬 이미지는 업로드되지 않으니 따로 호스팅하고 URL을 붙인다.

문서를 비공개로 둘 수 있나

그럴 수 있다. 비공개 워크스페이스 안 페이지에 배포하면 사내에만 남는다. 페이지를 공개로 공유하거나 Super를 앞에 두는 일은 따로 할 단계이고, 건너뛰어도 된다.

Windows에서도 되나

설치 스크립트는 macOS와 Linux만 확인하고 다른 시스템에서는 종료한다. Windows에서는 WSL이나 컨테이너를 써야 한다. 배포 결과는 어느 OS에서 만들었든 같다.

Notation에 자체 API가 있나

없다. 명령줄 도구가 사용자를 대신해 Notion API를 호출한다. 프로그램으로 배포하려면 Notation 엔드포인트 대신 스크립트나 CI 작업에서 바이너리를 실행한다.

Notation

Q: Notation은 어디에 쓰나

Markdown을 Notion으로 배포하는 도구다. .md 파일을 코드 저장소에 두고 notation ship 을 실행하면 지정한 Notion 페이지 안에 페이지 트리로 나타난다.

Kristian Gaylord · 코딩 · 학습

Notation은 Markdown 파일이 담긴 폴더를 Notion 페이지로 올리는 무료 오픈소스 CLI다. 저장소에서 문서를 쓰고 명령어 하나를 실행하면, Notion이 검색과 AI 기능 위에서 그 내용을 보여준다.

도구 방문

Notation 소개

About

Notation이란

Notation은 Markdown 파일이 가득한 디렉터리를 통째로 Notion 페이지에 밀어 넣는 작은 터미널 도구다. Rust로 작성했고 GPL-3.0으로 배포한다. notation ship --src를 실행하면 문서 폴더를 훑고 Notion 안에 페이지 트리를 다시 만든다.

생각은 단순하다. 문서 관리도 코드 옆에서 끝나야 한다. 기능 작업과 같은 pull request에서 .md를 고치면 리뷰하는 사람이 diff를 보고, CI가 배포 단계를 대신 실행한다. 병합 뒤에 다른 서비스에 로그인할 일이 없다.

쓰임새를 정하는 제약은 두 가지다. 목적지가 Notion 하나뿐이라 배포 대상은 항상 자기 페이지다. 동기화는 Markdown에서 Notion으로 한 방향만 흐르므로 저장소가 유일한 원본으로 남고, Notion에서 친 글은 되돌아오지 않는다.

시작하기

프로젝트 페이지의 셸 스크립트로 바이너리를 설치한다. 실행 파일은 ~/.notation에 들어가고 그 옆에 설정 파일 초안이 생긴다.
Notion에서 문서를 담을 페이지를 만들고, 설정 파일에 그대로 옮겨 적을 수 있는 이름을 붙인다.
설정과 멤버에서 내부 인티그레이션을 만들고 시크릿을 복사한다. 상위 페이지에서 연결에 그 인티그레이션을 추가해 쓰기 권한을 준다.
~/.notation/Notation.toml을 열고 인티그레이션의 secret과 parent_page 제목 두 값을 채운다.
저장소에서 notation ship --src /docs/경로를 실행한다. Notion에서 결과를 확인하고, 공개 사이트로 쓸 거면 페이지를 공유하거나 도메인을 연결한다.

제품 정보

Notation의 요금, 지원 플랫폼, 성능을 한눈에 확인해 보세요.

무료 플랜예

유료 플랜$0 (open source, GPL-3.0)

플랫폼macOS, Linux

개발사Kristian Gaylord

카테고리코딩 · 학습

출시일Jul 2024

최근 업데이트Aug 2024

웹사이트 방문 수7.1K

웹사이트 글로벌 순위2.8M

API 제공 여부아니요

주요 기능

명령어 하나로 폴더 배포

notation ship --src가 원본 디렉터리를 돌며 각 파일을 설정한 Notion 페이지에 쓴다. 빌드도, 생성한 사이트 배포도 없다. 병합에서 반영까지의 거리는 명령어 하나다.

폴더 구조가 페이지 구조가 된다

디렉터리는 하위 페이지가 되고 하위 디렉터리는 그 아래 페이지가 된다. 편집기에서 보는 트리가 독자가 보는 Notion 트리와 같다. 폴더 이름을 바꾸면 다음 배포에서 해당 페이지 이름도 바뀐다.

intro.md로 상위 페이지 채우기

문서 루트의 intro.md는 하위 페이지를 만들지 않고 내용을 상위 페이지에 바로 쓴다. 그래서 각 장에 글과 링크, 맥락이 있는 첫 페이지가 생긴다. 빈 컨테이너에 하위 페이지 목록만 붙는 일은 없다.

페이지별 제목과 이모지

Markdown 파일 맨 위에 --title과 --emoji를 적으면 Notion 페이지 이름과 아이콘을 정할 수 있다. setup.md를 로켓 이모지가 붙은 "Getting Started"로 내보낼 수 있다. 파일 이름은 기계에 맞게, 공개되는 제목은 사람이 읽기 좋게 유지된다.

사내 위키로도 공개 사이트로도

같은 대상을 워크스페이스 안 비공개 페이지로 두거나 공개 페이지로 공유할 수 있다. 자체 도메인을 쓰려면 공식 문서는 Super를 프런트엔드로 권한다. notation.so 자체도 그 구성으로 돌아간다.

Notion의 검색과 AI, 서식을 그대로

내용이 Notion에 들어가면 검색 인덱스, AI 답변, 목차, 블록 서식을 그대로 물려받는다. 많은 문서를 검색 가능하게 만드는 일은 어려운 문제인데, 여기서는 다른 쪽이 맡는다.

장단점

장점

GPL-3.0 무료 오픈소스라 좌석 수나 요금제, 페이지 한도를 신경 쓰지 않아도 된다.
문서가 저장소에 남아 코드 리뷰와 브랜치, CI가 추가 설정 없이 적용된다.
설치는 짧다. 바이너리를 넣고 Notion 인티그레이션을 만들고 값 두 개를 채우면 된다.
읽는 사람은 Notion에서 일한다. 검색과 댓글, AI 답변이 팀이 이미 켜 둔 도구에 딸려 온다.
결과물이 Notion에서 직접 만든 것처럼 보인다. 기술에 익숙하지 않은 독자도 Markdown에서 생성됐다고 알아채기 어렵다.

단점

동기화가 한 방향이다. Notion에서 고친 내용은 다음 배포에 덮어써지므로 쓰는 곳은 저장소 하나로 유지해야 한다.
이미지는 공개 URL이 필요하다. 로컬 파일은 업로드되지 않으니 다른 곳에 올리고 링크를 붙여야 한다.
사람마다 Notion 계정과 상위 페이지, 내부 인티그레이션 토큰이 필요하다. 첫 성공 전에 틀릴 수 있는 지점이 세 곳이다.
프로젝트가 작고 마지막 커밋이 2024년 8월이다. Notion API에 호환되지 않는 변경이 생기면 누군가 바이너리를 고쳐야 하고, 설치 스크립트는 Windows를 지원하지 않는다.