share-cards은(는) 무엇을 하나요?
미리보기 크롤러(채팅 앱, 소셜 사이트, 검색 엔진)는 서버가 보내는 HTML을 읽고 JavaScript를 실행하지 않습니다. 단일 페이지 앱(SPA)은 모든 주소에 동일한 HTML을 보내므로, 모든 링크가 같은 미리보기를 표시합니다. share-cards는 이 두 가지 문제를 해결합니다:
- 렌더링: 하나의 HTML 템플릿 + 페이지 목록 → 페이지별 1200x630 JPEG 이미지, 헤드리스 브라우저에서 생성.
- 주입: 빌드된
index.html→ 페이지별 HTML 파일, 각각 고유한<title>, description, canonical,og:*,twitter:*태그 포함.
스킬 폴더: ~/.claude/skills/share-cards/ (이하 $S). 모든 명령어는 $S/cards <command> [dir] 형태이며, [dir]에 cards.config.json이 있어야 합니다. $S/cards help 명령어로 목록을 확인할 수 있습니다.
$S/cards 명령줄 도구
$S/lib/ 설정, 태그 주입, 렌더링, 검증, 미리보기, 재작성 규칙
$S/templates/ editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs `vite build` 이후 inject 실행
$S/references/templates.md 슬롯, 변수 및 나만의 템플릿 작성 방법
$S/examples/site/ 4페이지로 구성된 예제 사이트 (카드 및 주입된 페이지 포함)
$S/README.md 설정 참조, 프레임워크 참고 사항, 제한 사항
워크플로우
- 머신 확인:
$S/cards check.render와preview명령어만 브라우저가 필요합니다. - 페이지 찾기: 프로젝트의 라우터 또는 콘텐츠 폴더를 읽고 모든 공개 주소를 나열하세요. 정적 파일이 제공되는 위치(
public/,static/)와 빌드 결과물이 생성되는 위치(dist/,build/,out/)를 찾으세요. - 스캐폴딩:
$S/cards init <project>(페이지 목록을 프로젝트 자체의 라우트나 콘텐츠 데이터에서 가져와야 해서 불일치가 발생하지 않도록 하려면--mjs플래그를 추가하세요).siteUrl(실제https://도메인),siteName,imageDir(정적 폴더 내 경로, 예:public/og),imageUrlPath(해당 폴더가 제공되는 URL 경로, 예:/og),dist를 설정하세요. - 각 페이지의 항목 작성:
title: 미리보기에 표시될 전체 페이지 제목.description: 한 문장, 최대 160자.cardTitle: 카드에 그려질 단어. 짧게 유지(약 2~6단어).*별표*는 강조 색상으로 그려질 단어를 표시합니다.cardDescription(선택 사항, 카드용 짧은 줄),kicker(작은 레이블),art(프로젝트의 이미지 파일),template(페이지별 재정의).- 이러한 항목에 대해 사실, 숫자, 인용문을 절대 지어내지 마세요. 페이지 자체의 단어를 사용하세요.
- 템플릿 및 테마 선택:
editorial(종이 질감, 두꺼운 세리프),minimal(흰색, 조용함),technical(어두운 배경, 고정폭 글꼴).theme을 프로젝트 자체 색상으로 설정하세요. 다른 템플릿이 필요하면$S/cards eject <name> card.html을 실행하고 편집한 후"template": "./card.html"로 설정하세요. 자세한 내용은references/templates.md를 참조하세요. - 렌더링:
$S/cards render <project>. 모든 경고를 읽으세요: 제목이나 설명이 잘리면 텍스트를 짧게 해야 합니다. - 결과 확인:
$S/cards preview <project>명령어는cards-preview/contact-sheet.png와chat-preview.png파일을 생성합니다. 두 PNG 파일을 모두 읽으세요. 각 카드에서 잘린 단어, 혼잡함, 대비 부족, 텍스트를 가리는 아트워크가 있는지 확인하세요. 수정 후 다시 렌더링하세요. 직접 확인하지 않고 사용자에게 카드가 올바르다고 말하지 마세요. - 페이지 셸 준비:
inject는 이미 존재하는 태그를 채우며, 태그가 없으면 실패합니다.$S/cards tags <project>를 실행하고 출력 블록을 소스index.html의<head>에 붙여넣어 기존 공유 태그를 대체하세요 (또는--add-missing플래그 사용). - 빌드에 연결:
- Vite:
$S/vite-plugin.mjs의shareCards()를plugins배열에 추가하세요 (README 참조). - 그 외: 빌드 명령어 후
$S/cards inject <project>를 실행하세요.
- Vite:
- 호스트 규칙: 호스트에
/index.html로의 catch-all 재작성 규칙이 있는 경우,$S/cards rewrites vercel|netlify|netlify-toml <project>명령어로 페이지 규칙을 출력하고 catch-all 앞에 배치하세요. 사용자에게 규칙을 보여주고, 동의 없이 호스트 설정을 편집하지 마세요. - 검증: 사이트를 빌드한 후
$S/cards verify <project>를 실행하세요.All good.메시지로 끝나야 합니다. - 남은 작업을 사용자에게 알리기: 배포 후, 채팅 앱에 실제 링크 하나를 붙여넣으세요. 미리보기는 각 앱에 의해 캐시되며, 때로는 며칠 동안 지속됩니다. 카드가 변경될 때마다 이미지 주소를 변경하려면
"versionImages": true를 설정하세요.
규칙
siteUrl은 프로덕션 도메인이어야 합니다. 미리보기 이미지는 절대https://주소가 필요합니다.- 빌드 전에 카드를 렌더링하여 빌드가 카드를 복사하도록 하고, 카드와
cards.lock.json을 커밋하세요. 그러면 CI에는 브라우저가 필요하지 않습니다. - 설정에
"allowNetwork": true가 설정되지 않은 경우 렌더링 중에 네트워크에서 아무것도 가져오지 않습니다. 웹 폰트는fonts아래에 나열된 로컬 파일이어야 합니다. - 폰트는 기본적으로 시스템 스택을 사용하므로, 다른 머신에서 그린 카드는 다를 수 있습니다. 모든 곳에서 동일한 출력을 원하면 폰트 파일을 프로젝트에 추가하고(라이선스 확인)
fonts아래에 나열하세요. - 확인되지 않은 사항을 명확히 말하세요: 각 앱의 실제 크롤러, 배포 후 호스트의 라우팅.