풀어쓰는 사회학 AI

홈
가이드

GitHub에서 교구 이미지·CSS 관리하는 법 | 파일 구조 정리 — 교사용 가이드

📌 이 글 요약

  • 교구가 늘어나면 이미지·CSS·JS 파일도 함께 늘어납니다. 폴더별로 정리하면 URL도 깔끔하고 관리도 편합니다.
  • GitHub 저장소에 images/, css/, js/ 폴더를 만들어 파일을 분류합니다.
  • 이미지는 raw URL 또는 GitHub Pages URL로 교구에서 참조할 수 있습니다.
  • CSS를 별도 파일로 분리하면 여러 교구가 같은 스타일을 공유할 수 있습니다.

교구가 늘어나면 이미지도 많아지잖아요. GitHub에 폴더별로 정리하면 URL도 깔끔하고 관리도 편합니다.

처음에는 교구 HTML 파일 하나로 끝났는데, 점점 이미지도 넣고, CSS도 꾸미고, JavaScript도 분리하고 싶어지더라고요. 그런데 파일을 전부 저장소 최상위에 올려놓으니까 금방 지저분해졌습니다. timer.html, quiz.html, logo.png, style.css, bg-pattern.jpg... 20개 넘어가니까 뭐가 뭔지 구분이 안 됐어요.

해결책은 간단합니다. 폴더를 만들어서 분류하면 됩니다. GitHub 저장소에서도 PC의 폴더와 똑같이 폴더 구조를 만들 수 있거든요.

추천 폴더 구조

교구 저장소를 깔끔하게 유지하려면 이런 구조를 추천합니다. 처음부터 이렇게 정리해 두면 나중에 교구가 30개, 50개로 늘어나도 관리가 수월해요.

my-tools/                    ← 저장소 루트
├── index.html               ← 허브 페이지 (교구 목록)
├── timer.html               ← 교구 파일들
├── quiz.html
├── word-match.html
├── images/                  ← 이미지 모아두는 폴더
│   ├── logo.png
│   ├── timer-bg.jpg
│   ├── quiz-icon.svg
│   └── badges/              ← 하위 폴더도 가능
│       ├── gold.png
│       └── silver.png
├── css/                     ← 공통 스타일
│   ├── common.css
│   └── quiz-theme.css
└── js/                      ← 공통 스크립트
    ├── utils.js
    └── confetti.js
폴더 넣는 파일 예시
images/PNG, JPG, SVG, GIF 등 이미지logo.png, timer-bg.jpg
css/스타일시트 파일common.css, quiz-theme.css
js/JavaScript 파일utils.js, confetti.js
(루트)교구 HTML 파일timer.html, quiz.html

✅ 핵심 포인트

  • 교구 HTML 파일은 루트에, 리소스 파일은 종류별 폴더에 넣습니다.
  • 폴더 이름은 영어 소문자로 통일하세요. 한글이나 대문자는 URL 문제가 생길 수 있습니다.
  • 이미지가 많아지면 images/badges/처럼 하위 폴더를 만들어도 됩니다.

GitHub에 이미지 업로드하기

GitHub 저장소에 이미지를 올리는 방법은 HTML 파일을 올리는 것과 동일합니다. 단, 폴더를 먼저 만들고 그 안에 업로드하는 과정만 다릅니다.

✅ 따라하기: images 폴더에 이미지 올리기

  1. GitHub 저장소 메인 페이지에서 "Add file" → "Create new file"을 클릭합니다.
  2. 파일 이름 입력란에 images/temp.txt를 입력합니다. 슬래시(/)를 쓰면 자동으로 폴더가 생성됩니다.
  3. 파일 내용에 아무 글자나 입력하고 "Commit changes"를 클릭합니다.
  4. 이제 images 폴더가 생겼습니다. 이 폴더로 이동합니다.
  5. "Add file" → "Upload files"를 클릭합니다.
  6. 이미지 파일들을 드래그앤드롭으로 올립니다. 한 번에 여러 개를 올려도 됩니다.
  7. "Commit changes"를 클릭하면 업로드 완료!

⚠️ 주의: GitHub에 올리는 개별 파일은 100MB 이하여야 합니다. 교구용 이미지는 대부분 몇 MB 이하니까 문제없지만, 고해상도 사진을 올릴 때는 미리 압축하세요.

💡 Tip: 아까 만든 temp.txt는 폴더를 만들기 위한 임시 파일입니다. 이미지를 올린 뒤에 삭제해도 되고, 그냥 둬도 상관없습니다.

이미지 URL 얻는 두 가지 방법

이미지를 올렸으면 교구에서 참조할 URL이 필요합니다. 방법이 두 가지 있는데, 같은 저장소 안에서는 상대 경로를 쓰고, 외부에서 참조할 때는 절대 URL을 씁니다.

방법 1: 상대 경로 (같은 저장소 안에서 — 권장)

교구 HTML 파일과 이미지가 같은 저장소에 있으면, 상대 경로를 쓰는 게 가장 간단합니다.

<!-- timer.html (루트에 있는 교구 파일) -->

<!-- images 폴더 안의 이미지 참조 -->
<img src="images/timer-bg.jpg" alt="타이머 배경">

<!-- images/badges 하위 폴더의 이미지 -->
<img src="images/badges/gold.png" alt="금메달">

<!-- css 폴더의 스타일 연결 -->
<link rel="stylesheet" href="css/common.css">

✅ 왜 상대 경로가 좋은가?

  • 저장소 이름이나 사용자 이름이 바뀌어도 경로를 수정할 필요가 없습니다.
  • 코드가 짧고 읽기 쉽습니다.
  • 로컬 PC에서 테스트할 때도 그대로 동작합니다.

방법 2: 절대 URL (외부에서 참조할 때)

블로그 글이나 다른 사이트에서 GitHub에 올린 이미지를 참조하려면 절대 URL이 필요합니다. 두 가지 URL 형태가 있어요.

종류 URL 형태 용도
GitHub Pages URL https://유저.github.io/저장소/images/logo.png 웹 페이지에서 이미지로 사용
Raw URL https://raw.githubusercontent.com/유저/저장소/main/images/logo.png 마크다운, 외부 사이트에서 직접 참조

✅ Raw URL 얻는 방법

  1. GitHub에서 이미지 파일을 클릭합니다.
  2. 이미지 미리보기 화면이 나타납니다.
  3. 이미지 위에서 마우스 우클릭 → "이미지 주소 복사"를 클릭합니다.
  4. 또는 "Download" 버튼을 우클릭하고 "링크 주소 복사"를 해도 됩니다.

💡 Tip: GitHub Pages가 활성화된 저장소라면 Pages URL을 쓰는 것을 추천합니다. raw.githubusercontent.com은 이미지 캐싱이 느리고, CORS 문제가 생길 수 있거든요.

교구에서 이미지 참조하기

이미지를 올리고 URL을 얻었으면, 교구 HTML 파일에서 사용하면 됩니다. 상황별 예시를 보겠습니다.

1. 교구 배경 이미지

<style>
  body {
    background-image: url('images/bg-pattern.jpg');
    background-size: cover;
    background-repeat: no-repeat;
  }
</style>

2. 퀴즈 정답 시 보상 이미지

<!-- HTML -->
<img id="badge" src="" alt="배지" style="display:none; width:120px;">

<script>
  function showBadge(type) {
    const badge = document.getElementById('badge');
    badge.src = 'images/badges/' + type + '.png';
    badge.style.display = 'block';
  }

  // 정답일 때
  showBadge('gold');    // images/badges/gold.png 표시
</script>

3. 로고 이미지

<header>
  <img src="images/logo.png" alt="교구 로고" style="height:48px;">
  <h1>김 선생님의 교구</h1>
</header>

CSS 파일 분리하기

교구를 여러 개 만들다 보면 매번 같은 CSS를 복사하게 됩니다. 버튼 색, 폰트, 레이아웃... 교구마다 똑같은 코드를 반복 작성하는 건 비효율적이에요. 이럴 때 공통 CSS를 별도 파일로 분리하면 한 곳만 수정해도 모든 교구에 적용됩니다.

공통 CSS 예시: common.css

/* css/common.css — 모든 교구가 공유하는 기본 스타일 */

:root {
  --primary: #2196F3;
  --success: #4CAF50;
  --danger: #f44336;
  --bg: #f5f7fa;
  --text: #1e1e1e;
  --card-bg: #ffffff;
}

* { margin: 0; padding: 0; box-sizing: border-box; }

body {
  font-family: 'Noto Sans KR', sans-serif;
  background: var(--bg);
  color: var(--text);
  padding: 40px 20px;
}

h1 {
  text-align: center;
  font-size: 24px;
  margin-bottom: 24px;
}

.btn {
  display: inline-block;
  padding: 10px 24px;
  border: none;
  border-radius: 8px;
  font-size: 16px;
  cursor: pointer;
  color: #fff;
}

.btn-primary { background: var(--primary); }
.btn-success { background: var(--success); }
.btn-danger  { background: var(--danger);  }
.btn:hover   { opacity: 0.85; }

교구에서 연결하기

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>발표 타이머</title>

  <!-- 공통 CSS 연결 -->
  <link rel="stylesheet" href="css/common.css">

  <!-- 이 교구 전용 스타일 (필요하면 추가) -->
  <style>
    .timer-display { font-size: 72px; text-align: center; }
  </style>
</head>
<body>

  <h1>발표 타이머</h1>
  <div class="timer-display">05:00</div>
  <button class="btn btn-primary">시작</button>
  <button class="btn btn-danger">초기화</button>

</body>
</html>

❌ CSS 분리 전

  • 교구마다 같은 CSS를 복사
  • 버튼 색을 바꾸려면 파일 10개를 수정
  • 실수로 하나만 빠뜨리면 디자인 불일치

✅ CSS 분리 후

  • common.css 한 줄만 연결
  • 색상 변경 시 CSS 파일 1개만 수정
  • 모든 교구의 디자인이 자동으로 통일

💡 팁: JavaScript도 분리할 수 있습니다

여러 교구에서 공통으로 쓰는 기능(효과음, 축하 애니메이션, 점수 계산 등)도 별도 JS 파일로 분리하면 재사용이 편합니다.

// js/utils.js — 여러 교구에서 공통으로 쓰는 함수

// 랜덤 셔플
function shuffle(array) {
  for (let i = array.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [array[i], array[j]] = [array[j], array[i]];
  }
  return array;
}

// 점수 퍼센트 계산
function calcPercent(correct, total) {
  return Math.round((correct / total) * 100);
}

// 결과 메시지
function getResultMessage(percent) {
  if (percent >= 90) return '훌륭합니다! 🏆';
  if (percent >= 70) return '잘했어요! 👏';
  if (percent >= 50) return '조금만 더! 💪';
  return '다시 도전해 보세요! 📚';
}
<!-- 교구 HTML에서 연결 -->
<script src="js/utils.js"></script>
<script>
  // utils.js의 함수를 바로 사용 가능
  const shuffled = shuffle(questions);
  const pct = calcPercent(score, total);
  alert(getResultMessage(pct));
</script>

💡 이미지 관리 팁 모음

팁 이유
파일 이름은 영어 소문자 + 하이픈한글 파일명은 URL 인코딩되어 길어지고, 오류의 원인이 됩니다. timer-bg.jpg 처럼 쓰세요.
용도를 파일 이름에 반영img1.png보다 quiz-correct-icon.png이 나중에 찾기 쉽습니다.
SVG를 적극 활용아이콘, 로고 등 단순한 그래픽은 SVG로 올리면 용량이 작고 확대해도 깨지지 않습니다.
이미지 압축 후 업로드TinyPNG 같은 사이트에서 먼저 압축하면 페이지 로딩이 빨라집니다.
alt 속성 반드시 작성<img src="..." alt="설명">에서 alt를 빈칸으로 두면 접근성이 떨어집니다.

⚠️ 주의: GitHub 저장소 전체 용량 권장 한도는 1GB입니다. 교구용 이미지를 수십 개 올리는 정도는 전혀 문제없지만, 고해상도 사진을 수백 장 올리면 한도에 근접할 수 있습니다. 대용량 이미지가 필요하면 외부 이미지 호스팅(Imgur, Cloudinary 등)을 병행하세요.

🎯 전체 흐름 정리

Step 1저장소에 images/ css/ js/ 폴더를 만든다
Step 2이미지 파일을 images/ 폴더에 업로드한다
Step 3교구 HTML에서 상대 경로로 이미지를 참조한다
Step 4공통 CSS를 별도 파일로 분리하고 <link>로 연결한다
Step 5GitHub에 커밋하고, GitHub Pages에서 확인한다

파일이 10개일 때는 폴더가 필요 없어 보이지만, 30개 넘어가면 폴더 없이는 관리가 안 됩니다. 지금 교구가 적더라도 처음부터 폴더 구조를 잡아두면 나중에 후회하지 않습니다. 이미지, CSS, JS를 분리해 두면 새 교구를 만들 때마다 복사할 코드가 줄어들고, 수정할 파일도 줄어듭니다.

현직 고교 교사가 전하는 통합사회·경제의 정석. 고퀄리티 수업 PPT와 HTML 시뮬레이션 교구, 생생한 여행 기록을 통해 사회를 풀어냅니다.