Communitygithub.com

imswarnil/Personal-Website-Jekyll-Theme

이 Jekyll 테마로 개인 웹사이트를 구축하세요 — 블로그, 포트폴리오, 비디오, 웹 시리즈, 강좌, 팟캐스트, 뉴스레터, 여행, 장비, 이력서를 포함하며 username.github.io에 GitHub Pages로 배포합니다. 누군가가 이 저장소로 자신의 사이트를 원하거나, 컬렉션을 추가하거나 재구성하고, 항목 페이지의 구성을 변경하거나, 처음으로 배포하려고 할 때 사용하세요.

Personal-Website-Jekyll-Theme란 무엇인가요?

이 스킬은 Jekyll 기반 개인 웹사이트 테마를 설치, 구성, 배포하는 과정을 안내합니다. 사용자는 블로그, 포트폴리오, 팟캐스트, 강좌 등 13가지 컬렉션을 쉽게 추가하고, 카드 디자인과 항목 페이지 구성을 레이아웃 편집 없이 설정 파일과 파일 추가만으로 변경할 수 있습니다. 대화형 셋업 위저드(`npm run setup`)가 identity, 색상, 내비게이션, 소셜 링크 등을 한 번에 설정하며, GitHub Actions를 통해 username.github.io로의 배포를 자동화합니다. Cli 환경에서 실행되며 Cursor, Claude Code 등 모든 터미널 기반 AI 에이전트와 호환됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imswarnil/Personal-Website-Jekyll-Theme/tree/HEAD/.claude/skills/personal-site

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

이 테마로 개인 사이트 구축하기

이 테마는 템플릿이 아닌 데이터로 구성됩니다. 사용자가 요청하는 거의 모든 변경 사항은 _config.yml 수정과 폴더에 파일 하나를 추가하는 것으로 해결됩니다. 레이아웃을 직접 수정하게 된다면, 이 문서를 먼저 확인하세요. 원하는 훅이 이미 존재할 가능성이 높습니다.

1. 가장 빠른 방법: 셋업 위저드

npm run setup          # 로컬 폼을 열고, _config.yml을 작성하며, 기존 파일을 백업합니다

위저드는 127.0.0.1에만 바인딩되며, 아무것도 업로드하지 않고, 대체되는 모든 파일을 먼저 .imprint-backup/<timestamp>/에 복사합니다. 현재 설정을 미리 채워주므로 나중에 다시 실행해도 안전합니다.

위저드는 identity, 강조 색상, 헤더와 푸터, 내비게이션, 소셜 링크, 컬렉션, 광고, 분석, 뉴스레터 엔드포인트, 도메인을 다룹니다. 컬렉션별 페이지 구성을 다루지 않으며 해당 키는 그대로 유지합니다(§4 참조).

그 다음:

npm run dev            # http://localhost:4000
npm run check          # doctor + 프로덕션 빌드

2. username.github.io에 배포하기

  1. 정확히 username.github.io라는 이름의 저장소를 만듭니다(사용자 페이지), 또는 프로젝트 페이지의 경우 아무 이름이나 사용합니다.
  2. 이 트리를 main 브랜치에 푸시합니다.
  3. Settings → Pages → Source: GitHub Actions.

.github/workflows/jekyll.yml은 Ruby 3.4로 빌드하고 _site/를 배포합니다. --baseurl "${{ steps.pages.outputs.base_path }}"를 전달하므로 동일한 워크플로가 사용자 페이지(빈 base path)와 프로젝트 페이지(/repo-name/) 모두에 올바르게 동작합니다 — baseurl을 하드코딩하지 마세요.

CNAME 파일이 사용자 정의 도메인을 저장합니다. 사용자 정의 도메인이 없으면 파일을 삭제하세요. 위저드는 도메인을 비워둘 때 자동으로 이 작업을 수행합니다.

3. 컬렉션 추가하기

컬렉션은 콘텐츠의 한 종류입니다: 블로그, 포트폴리오, 팟캐스트, 장비 목록 등. _config.yml의 collections: 아래에 추가하세요:

  recipes:
    output: true
    title: Recipes
    singular: Recipe
    description: "이 컬렉션에 대한 한 줄 설명."
    permalink: /recipes/:name/
    landing: /recipes/
    icon: cooking-pot          # phosphoricons.com의 이름 사용
    schema: Recipe             # schema.org 타입, JSON-LD용
    card: blog                 # 카드 디자인 (§5 참조)
    hero: { pattern: dots }    # 랜딩 페이지 히어로; `hero: false`로 간결한 헤더 사용
    image: "/assets/img/covers/recipes.svg"
    single:                    # 항목 페이지 구성 (§4 참조)
      lead: cover
      parts: [breadcrumbs, head, lead, prose, tags, share, ask, author, nav]
      widgets: [toc, collection, about]

그 다음:

mkdir _recipes                       # Jekyll이 읽는 폴더
# 목록을 표시하는 랜딩 페이지:
printf -- '---\nlayout: page\ntitle: Recipes\npermalink: /recipes/\nlist_collection: recipes\n---\n' > recipes.html
npm run thumbs                       # 새 컬렉션의 커버 아트를 생성합니다

npm run doctor를 실행하면 위 단계 중 누락된 것이 있는지 알려줍니다.

이 테마에는 13개의 컬렉션이 기본 포함됩니다: posts, portfolio, videos, snippets, prompts, webseries + episodes, courses + lessons, podcast, newsletter, travel, uses. 하위 컬렉션(에피소드, 레슨)은 프론트 매터의 slug를 통해 부모에 속합니다 — series: 또는 course:.

4. 항목 페이지 구성 변경하기

사람들이 보통 새 레이아웃이 필요하다고 생각하는 부분입니다. 하지만 그렇지 않습니다.

    single:
      lead: portfolio                 # _includes/leads/portfolio.html
      parts: [breadcrumbs, head, lead, prose, tags, share, ask, comments, author, nav]
      widgets: [details, toc, collection, cta]
      sidebar: true
  • parts → _includes/single/<name>.html, 지정된 순서대로 쌓입니다
  • widgets → _includes/widgets/<name>.html, 사이드바 아래로 배치됩니다
  • lead → _includes/leads/<name>.html (none으로 리드 없음)

파일을 추가하고 이름을 지정하는 것만으로 새 part를 만들 수 있습니다. 레이아웃을 수정할 필요가 없습니다. 모든 항목은 자체 프론트 매터에서 세 가지를 모두 재정의할 수 있습니다.

기본 제공되는 parts: breadcrumbs head toc-mobile lead prose tags share ask comments author nav episodes lessons siblings. Widgets: toc details collection about cta share subscribe ad. Leads: cover video prompt snippet portfolio series audio.

5. 카드 디자인

컬렉션의 card: <name>은 _includes/cards/<name>.html을 선택합니다. 기본 제공: blog(에디토리얼), portfolio(저장소 카드), video(플레이어), snippet(코드 창), prompt(채팅 창), webseries(세로 포스터), episode, course, lesson, podcast, issue, trip, product. 설정하지 않으면 blog로 fallback되므로 새 컬렉션도 자체 디자인이 없을 때 적절하게 보입니다.

그리드 행의 카드는 항상 같은 높이입니다. .im-cards는 각 항목을 늘리고 카드의 본문이 남은 공간을 채웁니다. 따라서 새 카드는 본문에 flex: 1을, 하단에 margin-top: auto만 설정하면 됩니다.

6. 태그 페이지

_plugins/tag_pages.rb는 모든 컬렉션에 걸쳐 /tags/<slug>/ 경로에 태그별 페이지를 생성합니다. Jekyll의 자체 site.tags는 포스트만 보기 때문에, 영화와 장비에도 태그가 달린 사이트에서는 실제 태그가 지정된 콘텐츠의 1/3만 표시됩니다. 태그는 slug로 그룹화되므로 Analytics와 analytics는 하나의 주제로 취급됩니다.

_plugins/ 생성기는 Jekyll이 우리에 의해 호출될 때마다 실행되며, .github/workflows/jekyll.yml이 그렇게 합니다. GitHub의 레거시 "브랜치에서 빌드" Pages 모드에서는 실행되지 않습니다. 해당 모드에서는 tag_pages: false로 설정하면 태그 링크가 /tags/의 앵커로 fallback됩니다.

7. 하우스 스타일 — CSS 작성 전에 읽어야 할 사항

이 테마는 Im Design System을 따르며, 정확히 두 가지 상호작용만 있습니다:

  • HOVER — 요소가 채워집니다(--im-hover-bg). 테두리가 선명해지거나, 3% 커지거나, 그림자에 의존하지 않습니다.
  • CURRENT — "현재 위치": 더 강한 채움과 더 굵은 레이블(--im-current-bg/-fg/-weight). 색상 변경이 아닙니다.

강조 색상(accent)은 기본 버튼, 링크의 호버, 포커스 링, 선택 영역, 각 컬렉션의 파생 색조에만 사용됩니다. 그 외에는 사용되지 않습니다. 채워진 버튼과 카드는 모두 정확히 1픽셀만 떠오르고 가는 실선 하나를 둡니다.

모든 것은 --im-* 커스텀 속성입니다. 리터럴 색상은 사용되지 않습니다. _sass/im/abstracts/_mixins.scss에 두 상호작용이 한 번만 정의되어 있습니다.

8. 명령어 모음

npm run setup     # 브라우저 셋업 폼
npm run dev       # 로컬 서버 + 라이브리로드
npm run build     # _site/로 프로덕션 빌드
npm run new       # 모든 컬렉션에 항목 스캐폴딩
npm run thumbs    # 강조 색상으로 생성된 커버 아트 (재)생성
npm run doctor    # 빌드를 망가뜨리는 설정 오류 검사
npm run test      # 설정/위저드 테스트 스위트
npm run check     # doctor + 빌드, 즉 CI가 수행하는 작업

Ruby 3.4가 필요합니다(.ruby-version 파일 참조). macOS 시스템 Ruby 2.6으로는 이 사이트를 빌드할 수 없습니다. bin/serve와 bin/build는 올바른 도구 체인을 PATH에 강제로 추가합니다.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬