깃허브 홈페이지에 글 올리기 – 메모장으로 md 파일 쓰고, 이미지·갤러리까지 한 번에

깃허브(GitHub)로 홈페이지를 만들고 나면 곧바로 이런 질문이 생깁니다. “워드프레스처럼 글쓰기 버튼이 없는데, 새 글은 어떻게 올리지?”, “사진은 어디에 넣어야 하지?”

답은 생각보다 간단합니다. 깃허브 홈페이지의 글은 md(마크다운) 파일 하나가 글 한 편입니다. 컴퓨터에 기본으로 들어 있는 메모장으로 글을 쓰고, 정해진 폴더에 올리기만 하면 깃허브가 알아서 웹페이지로 바꿔 줍니다.

이 글에서는 다음 네 가지를 차례대로 설명합니다.

1. 메모장으로 md 파일을 만들고 저장하는 방법
2. 글 안에 이미지를 넣는 코드
3. 갤러리에 사진을 올리는 방법
4. 각각 어느 폴더에 올려야 하는지

1. 먼저 알아두어야 할 폴더 구조

깃허브 홈페이지는 저장소(Repository) 안의 폴더 이름을 보고 “이건 글, 이건 사진” 하고 구분합니다. 이 글에서는 가장 널리 쓰이는 아래 구조를 기준으로 설명합니다.

한 줄로 정리하면 이렇습니다.

📌 폴더 이름 앞의 밑줄(_)은 꼭 붙여야 합니다

_posts의 맨 앞 밑줄(_)은 깃허브에게 “이 폴더는 글 보관함이야”라고 알려 주는 표시입니다. posts처럼 밑줄 없이 만들면 글로 인식되지 않습니다.

⚠️ 내 홈페이지 폴더 이름이 다르다면?

홈페이지를 만든 방식(테마)에 따라 이미지 폴더 이름이 images, img, assets/img 등으로 다를 수 있습니다. 이미 만들어진 폴더가 있다면 그 이름을 그대로 쓰시고, 아래 설명에서 폴더 이름만 바꿔 읽으시면 됩니다. 단, _posts는 어느 테마에서나 공통입니다.

2. 메모장으로 md 파일 만들기

2-1. 파일 확장자가 보이게 설정하기 (처음 한 번만)

윈도우는 기본적으로 파일 이름 끝의 .txt, .md 같은 확장자를 숨깁니다. 이 상태로 작업하면 글.md.txt처럼 엉뚱한 파일이 만들어지기 쉽습니다.

• 윈도우 11: 파일 탐색기 상단 보기 → 표시 → 파일 확장명 체크
• 윈도우 10: 파일 탐색기 상단 보기 탭 → 파일 확장명 체크

2-2. 파일 이름 규칙 – 가장 많이 틀리는 부분

_posts 폴더에 들어가는 글은 반드시 아래 형식으로 이름을 지어야 합니다.

연도-월-일-영문제목.md

올바른 예

• 2026-09-23-first-post.md
• 2026-10-01-hwacheon-sancheoneo-festival.md

잘못된 예

• 첫번째글.md → 날짜가 없어 글로 인식되지 않음
• 2026-9-23-first-post.md → 월·일은 반드시 두 자리(09, 03)
• 2026-09-23 first post.md → 띄어쓰기 대신 하이픈(-) 사용

💡 제목을 왜 영문으로 쓰나요?

파일 이름이 곧 인터넷 주소가 됩니다. 한글을 쓰면 주소가 %ED%99%94%EC%B2%9C…처럼 알아볼 수 없는 문자로 바뀝니다. 파일 이름은 영문 소문자로, 실제 글 제목은 파일 안에 한글로 적으면 됩니다.

2-3. 글의 맨 위에 ‘머리말’ 넣기

md 파일의 가장 윗부분에는 머리말(Front Matter)이라는 짧은 정보 묶음을 넣어야 합니다. 위아래를 하이픈 세 개(---)로 감싸는 부분입니다.

---
layout: post
title: "화천 파로호의 가을 풍경"
date: 2026-09-23
categories: 화천이야기
---

여기서부터 본문을 씁니다.

⚠️ 머리말은 반드시 파일 첫 줄에서 시작

--- 위에 빈 줄이나 공백이 하나라도 있으면 머리말로 인식되지 않고, 화면에 layout: post 같은 글자가 그대로 찍혀 나옵니다.

2-4. 본문 쓰는 기본 문법

메모장에서 아래처럼 기호를 붙여 쓰면, 홈페이지에서는 모양을 갖춘 글로 바뀝니다.

## 소제목입니다

첫 번째 문단입니다. 문단과 문단 사이에는
빈 줄을 한 줄 넣어야 합니다.

두 번째 문단입니다.

**굵은 글씨**와 *기울임 글씨*를 쓸 수 있습니다.

- 목록 첫째
- 목록 둘째

[화천군청 홈페이지](https://www.ihc.go.kr)

📌 줄바꿈이 안 된다면?

마크다운에서는 엔터를 한 번 치는 것만으로는 줄이 바뀌지 않습니다. 문단을 나누려면 빈 줄을 한 줄 넣고, 문단은 그대로 둔 채 줄만 바꾸려면 줄 끝에 공백 두 칸을 넣은 뒤 엔터를 칩니다.

2-5. 메모장에서 저장하기 – 이 세 가지만 확인하세요

메모장에서 파일 → 다른 이름으로 저장을 누른 뒤 아래 세 곳을 확인합니다.

1. 파일 형식: 텍스트 문서(*.txt)를 모든 파일(*.*)로 바꿉니다. 이걸 안 바꾸면 .md.txt 파일이 됩니다.
2. 파일 이름: 2026-09-23-first-post.md처럼 끝에 .md까지 직접 입력합니다.
3. 인코딩: UTF-8을 선택합니다. (ANSI로 저장하면 홈페이지에서 한글이 깨집니다.)

💡 윈도우 11 메모장은 기본값이 UTF-8

최신 메모장은 처음부터 UTF-8로 저장되지만, 저장 창 아래쪽 인코딩 칸을 한 번 눈으로 확인하는 습관을 들이시면 한글 깨짐 걱정이 없습니다.

3. 글 안에 이미지 넣기

3-1. 이미지 파일 준비

• 파일 이름은 영문 소문자와 하이픈만 사용합니다. 예: parho-lake-01.jpg
• 깃허브는 대문자와 소문자를 다른 글자로 구분합니다. 파일은 Photo.JPG인데 코드에 photo.jpg라고 쓰면 사진이 나오지 않습니다. 처음부터 전부 소문자로 통일하는 것이 가장 안전합니다.
• 스마트폰 원본 사진(보통 3~8MB)은 그대로 올리지 말고, 가로 1200~1600픽셀, 500KB 안팎으로 줄여서 올리세요. 홈페이지가 훨씬 빨리 열립니다. 윈도우 기본 ‘사진’ 앱이나 ‘그림판’의 크기 조정 기능으로 충분합니다.

3-2. 이미지를 넣는 기본 코드

사진을 assets/images/2026/ 폴더에 올렸다면, 글 본문의 원하는 위치에 아래 한 줄을 넣습니다.

![파로호 가을 풍경]({{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg)

구조를 풀어 보면 이렇습니다.

📌 ``은 왜 붙이나요?

홈페이지 주소가 your7179.github.io/book처럼 뒤에 저장소 이름이 붙는 형태라면, 이 코드가 없을 때 사진 경로가 어긋나 이미지가 깨집니다. 붙여 두면 주소 형태가 어떻든, 나중에 shinbook.kr 같은 도메인을 연결하더라도 그대로 작동합니다.

이 코드를 쓰려면 _config.yml 파일에 baseurl: "/book"(저장소 이름)이 적혀 있어야 합니다. 사용자이름.github.io 저장소라면 baseurl: ""로 비워 둡니다.

3-3. 사진 아래에 설명(캡션) 달기

사진 코드 바로 다음 줄에 기울임 글씨로 한 줄 적으면 캡션처럼 보입니다.

![파로호 가을 풍경]({{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg)
*10월 초 파로호 전망대에서 바라본 풍경*

3-4. 사진 크기를 직접 정하고 싶을 때

마크다운 기본 코드로는 크기를 정할 수 없습니다. 이럴 때는 md 파일 안에 HTML 코드를 그대로 섞어 쓰면 됩니다.

<img src="{{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg" alt="파로호 가을 풍경" width="600">

가운데 정렬까지 하려면 이렇게 감쌉니다.

<p align="center">
  <img src="{{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg" alt="파로호 가을 풍경" width="600">
</p>

3-5. 사진을 누르면 원본이 크게 열리게 하기

[![파로호 가을 풍경]({{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg)]({{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg)

이미지 코드 전체를 다시 한 번 링크 [ ]( )로 감싼 형태입니다.

3-6. 이미지가 들어간 글 전체 예시

---
layout: post
title: "화천 파로호의 가을 풍경"
date: 2026-09-23
categories: 화천이야기
---

올해도 파로호에 가을이 찾아왔습니다.

![파로호 가을 풍경]({{ site.baseurl }}/assets/images/2026/parho-lake-01.jpg)
*10월 초 파로호 전망대에서 바라본 풍경*

## 가는 길

화천읍에서 차로 20분 남짓 걸립니다.

<p align="center">
  <img src="{{ site.baseurl }}/assets/images/2026/parho-lake-02.jpg" alt="파로호 가는 길" width="600">
</p>

4. 갤러리에 사진 올리기

갤러리를 만드는 방법은 여러 가지가 있지만, 여기서는 사진을 폴더에 올리기만 하면 갤러리에 자동으로 나타나는 방식을 소개합니다. 한 번만 설정해 두면 그다음부터는 사진 업로드만 하면 됩니다.

4-1. 갤러리 페이지 만들기 (처음 한 번만)

저장소 맨 바깥(index.html이 있는 곳)에 gallery.html 파일을 만들고 아래 내용을 넣습니다.

---
layout: default
title: 갤러리
---

<h1>갤러리</h1>

<div class="gallery">
{% assign photos = site.static_files | where_exp: "f", "f.path contains '/assets/gallery/'" | sort: "modified_time" | reverse %}
{% for photo in photos %}
  <a href="{{ site.baseurl }}{{ photo.path }}" target="_blank">
    <img src="{{ site.baseurl }}{{ photo.path }}" alt="{{ photo.basename }}" loading="lazy">
  </a>
{% endfor %}
</div>

<style>
.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
  gap: 12px;
}
.gallery img {
  width: 100%;
  height: 200px;
  object-fit: cover;
  border-radius: 8px;
}
</style>

📌 이 코드가 하는 일

assets/gallery 폴더 안에 있는 사진을 전부 찾아서, 최근에 올린 순서대로 바둑판처럼 보여 줍니다. 사진을 누르면 원본이 새 창에서 크게 열립니다. 휴대전화에서는 한 줄에 한두 장, 컴퓨터에서는 서너 장씩 자동으로 배치됩니다.

4-2. 갤러리 사진 올리기 (매번 하는 작업)

이제부터는 사진을 assets/gallery 폴더에 올리기만 하면 됩니다. 코드는 건드릴 필요가 없습니다.

1. 깃허브 저장소 화면에서 assets → gallery 폴더를 차례로 클릭해 폴더 안으로 들어갑니다.
2. 오른쪽 위 Add file → Upload files를 누릅니다.
3. 사진 여러 장을 한꺼번에 끌어다 놓습니다.
4. 아래 Commit changes를 누릅니다.

⚠️ 반드시 폴더 안으로 들어간 뒤에 업로드

저장소 첫 화면에서 바로 Upload files를 누르면 사진이 맨 바깥에 흩어져 올라갑니다. 화면 위쪽 경로 표시가 내저장소 / assets / gallery로 되어 있는지 확인한 다음 올리세요.

💡 갤러리 사진의 파일 이름이 곧 설명이 됩니다

위 코드는 파일 이름을 사진 설명(alt)으로 사용합니다. img_2034.jpg보다 parho-lake-autumn.jpg처럼 내용을 알 수 있는 이름으로 올리면 검색엔진에도 도움이 됩니다.

5. 깃허브에 파일 올리는 방법 정리

5-1. 글(md 파일) 올리기

1. 저장소에서 _posts 폴더를 클릭해 들어갑니다.
2. Add file → Upload files
3. 메모장으로 저장한 md 파일을 끌어다 놓습니다.
4. Commit changes 클릭

5-2. 아직 없는 폴더를 새로 만들고 싶을 때

깃허브 웹 화면에는 ‘새 폴더’ 버튼이 없습니다. 대신 두 가지 방법이 있습니다.

방법 ① 컴퓨터에서 폴더째 끌어다 놓기 컴퓨터에 assets 폴더를 만들고 그 안에 images, gallery 폴더와 사진을 넣은 다음, assets 폴더 전체를 업로드 화면에 끌어다 놓으면 폴더 구조가 그대로 올라갑니다.

방법 ② 새 파일을 만들면서 폴더 이름 입력하기 Add file → Create new file을 누르고 파일 이름 칸에 assets/gallery/readme.txt처럼 입력합니다. 슬래시(/)를 치는 순간 앞부분이 폴더로 바뀝니다. 내용에 아무 글자나 한 줄 적고 Commit하면 폴더가 생깁니다.

📌 빈 폴더는 만들 수 없습니다

깃허브는 파일이 하나도 없는 폴더를 저장하지 않습니다. 그래서 방법 ②에서 readme.txt 같은 파일을 하나 넣어 주는 것입니다.

5-3. 이미 올린 글을 고치고 싶을 때

두 가지 중 편한 쪽을 쓰시면 됩니다.

• 깃허브 화면에서 바로 고치기: 해당 md 파일을 클릭 → 오른쪽 위 연필 아이콘 → 수정 → Commit changes
• 메모장으로 고쳐서 다시 올리기: 같은 이름의 파일을 다시 업로드하면 기존 파일이 새 내용으로 바뀝니다.

6. 올린 뒤 확인하기

Commit을 누른 뒤 바로 홈페이지에 반영되지는 않습니다. 보통 1~3분 기다려야 합니다.

진행 상황은 저장소 상단의 Actions 탭에서 볼 수 있습니다.

• 🟡 노란 점: 홈페이지를 새로 만드는 중
• ✅ 초록 체크: 반영 완료 – 홈페이지를 새로고침(Ctrl + F5)해 보세요
• ❌ 빨간 X: 오류 발생 – 대부분 머리말(---) 부분의 오타입니다

7. 자주 겪는 문제와 해결법

⚠️ .nojekyll 파일이란?

이 파일이 저장소에 있으면 깃허브가 md 파일을 웹페이지로 바꾸는 기능(지킬, Jekyll)을 꺼 버립니다. HTML만으로 홈페이지를 만들 때 넣어 두는 경우가 있는데, md 글을 쓰려면 반드시 지워야 합니다.

마치며

처음에는 폴더 이름, 파일 이름 규칙, 머리말 같은 것들이 낯설게 느껴질 수 있습니다. 하지만 정리해 보면 결국 세 가지뿐입니다.

• 글은 메모장으로 써서 UTF-8로 저장하고 → _posts 폴더에
• 글 속 사진은 영문 소문자 이름으로 → assets/images 폴더에
• 갤러리 사진은 그냥 → assets/gallery 폴더에

한두 번만 직접 해 보시면, 워드프레스 글쓰기 화면보다 오히려 더 단순하다는 것을 느끼실 겁니다. 무엇보다 이 모든 것이 평생 무료라는 점이 깃허브 홈페이지의 가장 큰 매력입니다.

깃허브로 무료 홈페이지 만들기 도서