노션 코드 블록 사용법 | 4단계 완벽 가이드

동료에게 코드를 공유할 때, 그냥 텍스트로 복사해서 붙여넣으신 적 있으신가요? 그럴 경우 들여쓰기(Indentation)가 깨지거나, 문법 강조(Syntax Highlighting)가 되지 않아 가독성이 매우 떨어지게 됩니다.

if문이 어디서 시작하고 끝나는지, 변수와 함수가 구분되지 않아 코드를 읽는 사람이 곤란해지곤 하죠.

이럴 때 필요한 기능이 바로 노션의 '코드 블록(Code Block)'입니다.

이 기능을 사용하면 VSCode 같은 에디터처럼 알록달록하게 문법을 강조해 주고, 코드 구조를 원본 그대로 유지할 수 있습니다.

오늘은 개발자뿐만 아니라 누구나 코드를 깔끔하게 기록하고 공유할 수 있는 노션 코드 블록의 4단계 사용법을 알려드릴게요.

노션 코드 블록, 언제 유용한가요?

단순히 텍스트로 적는 것보다 코드 블록을 사용하면 정보 전달력이 훨씬 높아집니다. 특히 아래와 같은 상황에서 필수적입니다.

기술 문서(Wiki) 작성: API 사용 예제나 서버 설정 가이드를 만들 때
협업 커뮤니케이션: 특정 코드 라인을 인용하여 리뷰하거나 피드백을 줄 때
개인 스니펫 저장: 자주 사용하는 SQL 쿼리문이나 단축 명령어를 저장해 둘 때

가장 큰 장점은 우측 상단에 복사 버튼이 자동으로 생성된다는 점입니다. 보는 사람이 드래그할 필요 없이 클릭 한 번으로 코드를 가져갈 수 있죠.

4단계로 끝내는 노션 코딩 (How-to) 🛠️

사용 방법은 매우 직관적입니다. 단축키를 활용하면 1초 만에도 가능합니다.

flowchart TD
    A[페이지 열기] --> B["/code 입력 또는
단축키 사용"]
    B --> C[언어 선택]
    C --> D[코드 작성/붙여넣기]

1단계: 페이지 이동 또는 생성

코드를 기록할 페이지를 엽니다. 새 페이지를 만들거나 기존 문서의 적절한 위치를 찾습니다.

팀과 공유할 문서라면 우측 상단 [공유] 버튼에서 권한 설정을 미리 체크해 주세요.

2단계: 코드 블록 소환하기

코드를 넣을 위치에 커서를 두고 /code 혹은 /코드를 입력한 뒤 [코드 블록]을 선택하세요.

단축키를 쓰면 더 빠르게 생성할 수 있습니다.

Mac: Cmd + Option + 8
Windows: Ctrl + Shift + 8

노션 페이지에서 슬래시(/) 명령어를 입력하여 나타난 메뉴 화면. 검색창에 '/코드'를 입력했을 때 나타나는 '코드' 블록 옵션을 빨간색 화살표가 가리키며 선택하는 모습

💡 팁: 코드를 먼저 붙여넣고 블록을 씌우려 하기보다, 빈 코드 블록을 먼저 만들고 그 안에 붙여넣어야 포맷 유지에 유리합니다.

3단계: 프로그래밍 언어 선택 (중요 ⭐)

블록 좌측 상단에 기본적으로 JavaScript 혹은 일반 텍스트(Plain Text)라고 적혀 있을 겁니다. 이 부분을 클릭해서 작성할 언어를 선택하세요. (Python, Java, SQL, HTML 등 60개 이상 지원)

생성된 노션 코드 블록의 언어 설정 드롭다운 메뉴. 빨간색 박스로 언어 목록을 강조하고 있으며, 다양한 프로그래밍 언어 중 'Python'을 선택하여 문법 강조 기능을 활성화하는 화면

언어를 정확히 선택해야 노션이 문법을 인식하여 색상 강조(Syntax Highlighting)를 적용해 줍니다. 가독성이 완전히 달라지죠.

4단계: 작성 및 복사

이제 블록 안에 코드를 입력하거나, 다른 에디터에서 복사한 내용을 붙여넣으세요. 들여쓰기와 괄호 짝 맞추기가 자동으로 지원되어 구조가 깔끔하게 유지됩니다.

문서를 더 깔끔하게 만드는 활용 팁 3가지 🍯

기본 기능만 써도 충분하지만, 문서를 더 전문적으로 보이게 만드는 기능들도 있습니다.

1. 캡션(Caption)으로 설명 달기 코드만 덩그러니 있으면 어떤 기능을 하는지 알기 어렵습니다. 코드 블록 위 마우스를 올리고 ⋮⋮ → 캡션을 눌러 부가 설명을 추가하세요. 예: "API 요청 예제 - 인증 토큰 필수"

코드 블록 왼쪽의 6점 아이콘(⋮⋮)을 클릭했을 때 나타나는 옵션 메뉴. 빨간색 화살표가 '캡션(Caption)' 항목을 가리키고 있으며, 이를 통해 코드 아래에 부가 설명을 추가할 수 있음을 보여줌

2. 토글(Toggle)로 깔끔하게 정리 코드가 100줄이 넘어가면 문서의 스크롤이 너무 길어집니다. /토글을 입력해 토글 블록을 만들고, 그 안에 코드 블록을 넣어보세요. 필요할 때만 펼쳐볼 수 있어 문서가 훨씬 깔끔해집니다.

3. 배경색으로 상태 구분하기 코드 블록 자체에도 배경색을 지정할 수 있습니다.

빨간색 배경: 에러 로그나 잘못된 예시
초록색 배경: 정상 작동 코드나 모범 답안 이렇게 색상으로 구분하면 직관적인 가이드 문서를 만들 수 있습니다.

자주 묻는 질문 (FAQ) 💬

Q. 노션에서 코드가 실제로 실행되나요?

A. 아니요, 노션 코드 블록은 코드를 보여주는 '뷰어(Viewer)' 역할만 합니다. 코드를 실행하려면 Replit 같은 외부 도구를 임베드(Embed)해야 합니다.

Q. 코드 내용만 따로 복사할 수 있나요?

A. 네! 코드 블록 우측 상단에 마우스를 올리면 [복사] 아이콘이 나타납니다. 드래그할 필요 없이 클릭 한 번이면 클립보드에 저장됩니다.

기술 블로그, 노션으로 시작하세요

코드 블록 기능 덕분에 노션은 개발자와 비개발자 모두에게 훌륭한 협업 도구가 되었습니다. 마크다운보다 직관적이고, 깃허브보다 공유하기 편하니까요.

오늘 당장 자주 쓰는 SQL 쿼리나 터미널 명령어를 노션에 저장해 보세요. 나중엔 든든한 나만의 코드 라이브러리가 될 것입니다.

혹시 이렇게 정리한 기술 문서들, 팀 내부에서만 보기 아깝지 않으신가요?

D-SKET에서 블로그 템플릿을 활용해서 노션 페이지를 멋진 기술 블로그로 5분 만에 변신시킬 수 있습니다.

여러분의 개발 지식 공유, 이제 더 멋지게 시작해보세요! 👋

노션 코드 블록 작성법 4단계: 코드를 깔끔하게 공유하는 법 (단축키 포함)