--- title: GitHub Pages에서 .md 파일이 404 나는 Jekyll 지옥 탈출기 description: 몇 시간 삽질한 끝에 발견한 GitHub Pages의 숨겨진 Jekyll 처리 함정과 .nojekyll 파일의 진실 date: 2024-11-29 tags: [GitHub Pages, Jekyll, 삽질기록, 404에러, .nojekyll, 마크다운] ---

GitHub Pages에서 .md 파일이 404 나는 Jekyll 지옥 탈출기

바닐라 JS로 블로그 만들면서 겪은 가장 황당한 버그. 몇 시간 삽질한 끝에 알게 된 GitHub Pages의 숨겨진 함정과 왜 .md 대신 .txt를 써야 하는지 정리.

문제 발생: .md 파일이 404

상황

블로그 시스템을 만들면서 게시물을 .md 파일로 저장했다.


posts/
├── web/
│   ├── chrome-devtools-protocol.md
│   └── giscus-comment.md
├── playground/
│   └── neon-breakout.md
└── index.json

로컬에서는 완벽하게 작동했는데, GitHub Pages에 배포하니까 모든 .md 파일이 404 에러!


// 이 코드가 로컬에서는 잘 되는데...
fetch('posts/web/chrome-devtools-protocol.md')
    .then(response => response.text())
    .then(content => console.log(content));

GitHub Pages에서는:


GET https://username.github.io/posts/web/chrome-devtools-protocol.md
404 Not Found

첫 번째 삽질: 경로 문제인 줄 알았음


// 절대경로로 바꿔보기
fetch('/posts/web/chrome-devtools-protocol.md')

// 상대경로 다시 확인
fetch('./posts/web/chrome-devtools-protocol.md')

// URL 인코딩까지 해보기
fetch(encodeURIComponent('posts/web/chrome-devtools-protocol.md'))

결과: 여전히 404

두 번째 삽질: 캐시 문제인 줄 알았음

30분 기다림

캐시 무효화 시도

하드 리프레시 (Ctrl + Shift + R)

다른 브라우저에서 테스트

결과: 여전히 404

세 번째 삽질: MIME 타입 문제인 줄 알았음


// fetch 헤더 확인해보기
fetch('posts/web/chrome-devtools-protocol.md')
    .then(response => {
        console.log('Status:', response.status);
        console.log('Headers:', response.headers);
        return response.text();
    });

여전히 404인데, 다른 정적 파일들(.css, .js, .json)은 잘 됨. 뭔가 .md 파일만 특별히 안 되는 거 같은데...?

해결책 발견: .txt로 바꾸니까 됨

절망적인 마음으로 확장자를 .txt로 바꿔봤다.


posts/
├── web/
│   ├── chrome-devtools-protocol.txt  ← .md에서 변경
│   └── giscus-comment.txt            ← .md에서 변경
├── playground/
│   └── neon-breakout.txt             ← .md에서 변경
└── index.json

결과: 완벽하게 작동!


fetch('posts/web/chrome-devtools-protocol.txt')
    .then(response => response.text())
    .then(content => {
        console.log('드디어 된다!', content);
    });

진실 파헤치기: 왜 .md는 안 되고 .txt는 될까?

Jekyll의 숨겨진 마크다운 처리

조사해보니 충격적인 사실 발견: > GitHub Pages는 Jekyll을 사용하지 않는 저장소에서도 기본적으로 모든 파일을 Jekyll로 처리한다. #### Jekyll이 .md 파일에게 하는 일

.md 파일을 발견하면 "마크다운이네! HTML로 변환해야지!"

Front Matter 파싱 시도 (---로 시작하는 YAML)

마크다운 → HTML 변환 시도

변환 결과를 다른 경로에 저장 (보통 .html로)

#### 우리 블로그의 .md 파일 구조


---
title: Chrome DevTools Protocol로 브라우저 제어하기
description: CDP를 이용해서 Chrome과 Edge 브라우저를 프로그래밍 방식으로 제어하는 방법
date: 2024-11-29
tags: [CDP, 브라우저 제어, Chrome, Edge, JavaScript, Node.js]
---

# Chrome DevTools Protocol로 브라우저 제어하기
...

Jekyll이 보기에는:

"Front Matter가 있는 마크다운 파일이네!"

"HTML로 변환해서 /posts/web/chrome-devtools-protocol/ 같은 경로에 저장해야지!"

원래 .md 파일은 더 이상 접근 불가능

그런데 우리는 원본 .md 파일을 fetch()로 직접 가져오려고 했으니까 당연히 404.

.txt 파일은 왜 됐을까?

Jekyll은 .txt 파일을 마크다운으로 인식하지 않는다.

Jekyll: "텍스트 파일이네, 그냥 두자"

원본 파일이 그대로 유지됨

fetch()로 접근 가능

.nojekyll 파일의 진실

우리 프로젝트 루트에 .nojekyll 파일이 있다.


D:\_00_gitpage\ramgaku.github.io\.nojekyll

"이게 있으면 Jekyll 처리를 안 한다고 했는데 왜 .md 파일이 404 났지?"

.nojekyll의 실제 역할 범위

조사해보니 .nojekyll 파일은:

Jekyll 빌드 프로세스 비활성화 (테마, 플러그인 등)

_로 시작하는 파일/폴더 무시 방지

마크다운 파일 변환 처리는 여전히 발생

즉, Jekyll의 핵심 마크다운 처리 엔진은 여전히 동작한다.

GitHub의 공식 문서에 나와있는 함정


By default, GitHub Pages runs all files through Jekyll
(even if your repository is not set up to use Jekyll).

.nojekyll이 있어도 마크다운 처리는 계속 된다는 뜻.

다른 해결책들

1. 다른 확장자 사용


.txt   - 잘 됨
.md    - Jekyll 처리됨
.mdx   - 잘 됨
.data  - 잘 됨

2. Jekyll Front Matter 제거

마크다운 파일에서 --- Front Matter를 제거하면 Jekyll이 무시할 수도 있음. (하지만 불확실)

3. GitHub Actions로 커스텀 배포

Jekyll 대신 GitHub Actions로 직접 배포하면 완전히 우회 가능.


# .github/workflows/pages.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

교훈과 해결책

왜 .txt를 강력 추천하는가?

안정성: Jekyll 처리 완전 회피

예측 가능성: 파일이 있는 그대로 서빙됨

호환성: 모든 정적 서버에서 동작

단순성: 추가 설정 불필요

비슷한 상황에 처한 개발자들에게

증상 체크리스트

로컬에서는 잘 되는데 GitHub Pages에서 404

.md, .markdown 확장자 파일들만 404

다른 정적 파일(.css, .js, .json)은 잘 됨

.nojekyll 파일이 있는데도 문제 발생

→ Jekyll 마크다운 처리가 원인일 확률 95%

빠른 해결법

확장자를 .txt로 변경 (가장 간단)

Front Matter 제거 시도

GitHub Actions 커스텀 배포 (고급)

예방법

프로젝트 문서에 다음과 같은 경고를 추가하는 것을 추천:


# README.md 또는 프로젝트 문서에 추가
- **절대 .md 확장자 사용 금지** - GitHub Pages Jekyll 처리 때문에 404 발생
- 반드시 .txt 사용할 것

그럼 왜 다른 사람들은 .md 잘 쓰는데?

대부분의 GitHub Pages 블로그는:

Jekyll을 정식으로 사용 - 마크다운이 HTML로 변환되어 정상 동작

GitHub Actions 커스텀 배포 - Jekyll 우회

다른 정적 사이트 도구 사용 (Gatsby, Next.js 등)

우리처럼 바닐라 JS로 fetch()를 써서 원본 마크다운을 직접 가져오는 경우는 드물다.

정리

이 몇 시간의 삽질 덕분에:

GitHub Pages Jekyll 처리 메커니즘 이해

.nojekyll 파일의 실제 역할 파악

안정적인 블로그 시스템 구축

다른 개발자들에게 도움이 될 지식 획득

삽질도 가치 있는 학습이다. 특히 GitHub Pages 같은 플랫폼은 문서에 없는 숨겨진 동작들이 많아서, 직접 부딪혀봐야 알 수 있는 것들이 많다. --- 혹시 비슷한 문제로 고생하고 있다면, .txt 확장자를 써보자. 진짜 된다.

github-pages-markdown-404-hell