Embed & 미디어 블록
Notion 페이지의 이미지, 비디오, 외부 콘텐츠 임베드 등 미디어 블록이 어떻게 렌더링되는지 설명합니다.
이미지 블록
Notion에서 이미지를 추가하면, React에서 <img> 태그로 렌더링됩니다.
자동 적용되는 최적화
| 기능 | 설명 |
|---|---|
| Lazy Loading | 화면에 보일 때만 로드 (loading="lazy") |
| 비동기 디코딩 | 페이지 렌더링 차단 안 함 (decoding="async") |
| 반응형 | 컨테이너에 맞춰 자동 크기 조정 |
Notion에서 이렇게 하면 됩니다
- Notion 페이지에서
/image입력 - 이미지 업로드 또는 URL 붙여넣기
- 끝! 자동으로 렌더링됩니다
주의사항
Notion 이미지 만료
Notion에 업로드된 이미지는 1시간 후 URL이 만료됩니다.
프로덕션에서는 이미지를 별도 스토리지(S3, Cloudinary 등)에 저장하는 것을 권장합니다.
비디오 블록
YouTube, Vimeo 등 동영상 링크를 iframe으로 임베드합니다.
지원되는 플랫폼
| 플랫폼 | 자동 변환 |
|---|---|
| YouTube | ✅ |
| Vimeo | ✅ |
| 기타 | URL 그대로 사용 |
렌더링 결과
- 16:9 비율 유지 (반응형)
- caption이 있으면 아래에 표시
Notion에서 이렇게 하면 됩니다
- Notion 페이지에서
/video입력 - YouTube/Vimeo URL 붙여넣기
- 자동으로 임베드 플레이어로 렌더링
Embed 블록
외부 서비스를 iframe으로 삽입할 때 사용합니다.
언제 쓰나요?
- Figma 디자인 임베드
- Google Maps 지도 삽입
- CodePen, CodeSandbox 코드 데모
- Spotify, SoundCloud 플레이어
- 기타 iframe을 지원하는 모든 서비스
렌더링 형태
| 속성 | 값 |
|---|---|
| 높이 | 1200px (고정) |
| 너비 | 부모 컨테이너 100% |
| 테두리 | 1px 테두리 + 8px 둥글기 |
Notion에서 이렇게 하면 됩니다
- Notion 페이지에서
/embed입력 - 외부 서비스 URL 붙여넣기
- 자동으로 iframe 렌더링
임베드가 안 되는 경우
일부 서비스는 iframe 삽입을 차단합니다:
X-Frame-Options헤더로 차단Content-Security-Policy로 차단
이런 경우 Notion 자체에서도 임베드가 제한됩니다.
해당 서비스에서 "임베드 코드"를 별도로 제공하는지 확인하세요.
Bookmark 블록
링크를 카드 형태로 보여줍니다.
렌더링 결과
- URL + 제목이 카드로 표시
- 클릭하면 새 탭에서 링크 열림
Notion에서 이렇게 하면 됩니다
- URL을 복사해서 붙여넣기
- "Create bookmark" 선택
- 카드 형태로 렌더링
코드 블록
**문법 강조(Syntax Highlighting)**가 적용된 코드 블록입니다.
기능
| 기능 | 설명 |
|---|---|
| 문법 강조 | 언어별 색상 |
| 복사 버튼 | 클릭하면 코드 복사 |
| 언어 표시 | 우측 상단에 언어명 |
Notion에서 이렇게 하면 됩니다
/code입력- 코드 작성
- 언어 선택 (JavaScript, Python 등)
미디어 블록 정리
| 블록 | 렌더링 | 특징 |
|---|---|---|
image | <img> | lazy loading, 반응형 |
video | <iframe> | 16:9, YouTube/Vimeo 자동 변환 |
embed | <iframe> | 1200px 높이, 외부 서비스 임베드 |
bookmark | 링크 카드 | 새 탭에서 열림 |
code | 코드 블록 | 문법 강조 + 복사 버튼 |
자주 묻는 질문
Q. 이미지가 너무 크게/작게 보여요
이미지는 컨테이너 너비에 맞춰 자동 조정됩니다.
컨테이너의 max-width를 조정하세요.
Q. Embed 높이를 바꾸고 싶어요
현재 버전(0.1.1)에서는 1200px 고정입니다.
추후 embedOptions로 커스터마이징할 수 있도록 업데이트 예정입니다.
Q. YouTube 동영상이 재생 안 돼요
- URL 형식 확인 (youtu.be 또는 youtube.com/watch?v=...)
- 동영상이 임베드 허용되어 있는지 확인
- 브라우저 확장 프로그램이 차단하지 않는지 확인