Content Widgets
콘텐츠 블록으로 쓰는 문서 위젯: 알림, 아코디언, 탭, 단계, 제품 박스, 임베드, 코드, 카드, 인용문, 목차, 최신 게시물.
플러그인
Content Widgets
콘텐츠 블록으로 쓰는 문서 위젯: 알림, 아코디언, 탭, 단계, 제품 박스, 임베드, 코드, 카드, 인용문, 목차, 최신 게시물.
설명
Content Widgets
라이브 데모: emdashhq.com/blog/widget-gallery — 열아홉 개 위젯을 모두 한 기사에서 렌더링합니다.
EmDash 사이트를 위한 기사 위젯 모음: 콜아웃, 아코디언, 탭, 체크리스트, 버튼, YouTube 및 iframe 임베드, 제품/리뷰 박스, 풀 쿼트, 팩트 표, 자동 목차, 시리즈 탐색, 그리고 실시간 “최신 게시물” 목록.
각 위젯은 blocks 필드의 블록 유형이므로, 스키마가 허용하는 한 페이지 콘텐츠, 블로그 게시물 본문, 랜딩 페이지 등 블록 기반 필드 어디에나 편집자가 끌어다 놓을 수 있습니다.
포함된 것
모두 widget_ 접두사가 붙은 열아홉 가지 블록 유형: Prose, Notice, Accordion, Tabs, Checklist, Steps, Button, YouTube, Embed, Image, Code, Product box, Link cards, Pull quote, Facts table, Table of contents, Series nav, Latest posts, Divider.
작동 방식
샌드박스 플러그인은 Astro 렌더 컴포넌트를 함께 제공할 수 없으므로, 위젯은 패키지의 site/ 디렉터리 안에 블록 유형 JSON과 바로 쓸 수 있는 Astro 컴포넌트로 배포됩니다. 사이트에 한 번만 복사하면 됩니다. YouTube의 개인정보 모드, 제휴 공개 문구, 게시물 쿼리 같은 공유 런타임 동작은 컴포넌트가 프로세스 안에서 호출하는 두 개의 공개 라우트를 통해 플러그인이 제공하며, HTTP 왕복이 없습니다.
플러그인은 또한 모든 블록의 필드를 설명하는 Widget catalog 관리자 페이지와, 정확한 설치 단계와 설정 상태를 보여주는 Setup guide 페이지를 추가합니다.
설치
설치
1. 플러그인 설치
EmDash 플러그인 레지스트리에서 @bitdoze.com/emdashhq-widgets를 설치하거나, 파일 의존성으로 연결하고 astro.config.mjs의 sandboxed: 아래에 등록합니다.
import widgetsPlugin from "emdashhq-widgets";
emdash();플러그인은 content:read와 schema:read를 요청합니다. Latest posts 위젯과 posts 라우트가 작동하도록 승인하세요. 정적 위젯은 승인하지 않아도 렌더링됩니다.
2. 스키마에 블록 유형 추가
site/block-types/*.json을 시드 파일의 blockTypes 배열에 복사하고(또는 운영 중인 사이트에서는 각 파일의 내용을 /_emdash/api/schema/block-types에 POST하고), 이를 받아야 하는 blocks 필드(예: pages.content 또는 posts.body)의 allowedTypes에 해당 유형을 나열합니다.
3. 렌더러 등록
site/components/*.astro, site/components/config.ts, site/components/icons.ts, site/widget-components.ts, site/WidgetBlocks.astro를 프로젝트에 복사한 다음, 위젯 전용 필드에는 WidgetBlocks를 렌더링합니다.
또는 기존 맵에 widgetComponents를 펼쳐 넣습니다.
const blockComponents = defineBlockComponents();4. 구성
설정은 Plugins → Content Widgets → Settings에 있습니다.
- Privacy-enhanced YouTube embeds — 플레이어를
youtube-nocookie.com에서 제공합니다(기본값은 켜짐). - Affiliate disclosure — Product box 위젯 안의 작은 글씨 줄이며, 비워 두면 숨겨집니다.
- Posts collection — Latest posts 위젯과
posts라우트의 기본 컬렉션.
자주 묻는 질문
자주 묻는 질문
왜 플러그인이 대신 해주지 않고 파일을 복사해야 하나요?
샌드박스 플러그인은 격리된 런타임에서 실행되며 Astro 렌더 컴포넌트를 등록할 수 없습니다. site/ 디렉터리에는 플러그인 작성자가 쓰는 것과 같은 블록 유형 JSON과 컴포넌트가 들어 있으므로, 설치는 저장소에 한 번 복사하는 것으로 끝납니다. 그 후에는 위젯이 직접 만든 블록 유형처럼 동작합니다.
플러그인을 설치하지 않아도 위젯이 작동하나요? 정적인 것은 작동합니다. Prose, Notice, Accordion, Tabs, Checklist, Button, Embed, Quote, Facts, TOC, Series는 블록 유형과 컴포넌트만 있으면 됩니다. YouTube, Product box, Latest posts는 플러그인 설정이나 라우트를 읽으며, 플러그인이 없으면 기본값(쿠키 없음 켜짐, 공개 문구 없음, 빈 목록)으로 돌아갑니다.
YouTube 위젯이 쿠키를 설정하나요?
방문자가 썸네일을 클릭하기 전에는 어떤 플레이어도 로드되지 않습니다. 기본 개인정보 설정에서는 플레이어가 youtube-nocookie.com에서 오며, 그때도 추적 쿠키를 설정하지 않습니다.
Latest posts는 목록을 어떻게 만드나요?
컴포넌트가 플러그인의 공개 posts 라우트를 프로세스 안에서 호출합니다(HTTP 요청 없음). 이 라우트는 구성된 컬렉션에서 게시된 항목을 최신순으로 나열하고, 각 항목의 공개 URL을 컬렉션의 urlPattern에서 해석합니다.
위젯의 스타일을 바꿀 수 있나요?
네. 모든 컴포넌트는 wgt-* 클래스를 사용하고 디자인 토큰(--color-brand, --color-surface 등)을 중립적인 대체값과 함께 읽습니다. 클래스나 토큰을 덮어써서 테마에 맞추세요.
일반 페이지 안에서도 위젯이 작동하나요?
네. 어떤 blocks 필드의 allowedTypes에든 widget_* 유형을 추가하세요. 페이지, 게시물, 그 밖의 무엇이든 가능합니다.
변경 내역
변경 내역
1.0.4
- JavaScript 없는 탭: 라벨은 페이지 내 앵커로 대체되고 모든 패널이 계속 보입니다. JS가 있으면 화살표 키, Home/End, 로빙 tabindex를 지원하는 실제 탭으로 업그레이드됩니다.
- 문서: 갤러리 데모 링크에 UTM 매개변수를 붙였습니다.
1.0.3
- Product box: 이미지가 없는 레이아웃에서 콘텐츠가 좁은 열로 몰리던 문제를 수정했습니다. 미디어 열은 이제 이미지가 설정된 경우에만 렌더링됩니다
- Product box 스타일 개편: 고정폭 글꼴의 공개 문구 줄, 가격 칩, 장단점의 체크/엑스 표시, 사이트 버튼과 같은 스타일의 버튼
- 사이트 아이콘 세트에 단점 열용
x아이콘이 추가되었습니다
1.0.2
- 문서: 설명에서 라이브 위젯 갤러리 데모 게시물로 연결
1.0.1
- 레지스트리 목록용 자산: 플러그인 아이콘, 배너, 스크린샷
- 문서 수정: 설명과 변경 내역의 19개 블록 목록
1.0.0
- 첫 릴리스: 19가지
widget_*블록 유형(prose, notice, accordion, tabs, checklist, steps, button, YouTube, embed, image, code, product, link cards, quote, facts, table of contents, series nav, latest posts, divider) site/아래의 블록 유형 JSON과 독립형 Astro 컴포넌트- 공유 설정(YouTube 개인정보 모드, 제휴 공개 문구, 게시물 컬렉션)을 위한 공개
config라우트 - 해석된 URL과 함께 최신 게시 항목을 나열하는 공개
posts라우트 - Block Kit 관리자 페이지: 위젯 카탈로그와 설정 가이드