Jekyll Basic 2

Tools github-blog
#jekyll #github_pages #study-bloging

jekyll에서는 레이아웃을 이용해서 HTML을 렌더링하는데요, 다른 사람의 레포지토리를 기워서 블로그를 만들때 이 부분이 꼬여서 한참 고생했던 경험이 있습니다. 그래서 이번에는 .. 잘 공부해서 만들어봅니다..

레이아웃이란?

레이아웃은 같은 구조의 페이지들을 효율적으로 관리할 수 있도록 해줍니다. 웹페이지의 HTML 템플릿으로, 마크다운 파일의 내용을 감싸서 완성된 웹 사이트로 만들어주는 역할을 합니다.

여기서 템플릿 엔진이라는 개념이 사용되는데, MD 와 레이아웃이 결합되어서 HTML 사이트를 만들어주는 역할을 합니다.

예를 들어 이런 마크다운 페이지가 있습니다.

/---
layout: post
title: "내 첫 포스트"
/---

# 안녕하세요!

이것은 마크다운 내용입니다.

이 마크다운에서 레이아웃을 post로 지정했고, 레이아웃 html파일은 다음과 같습니다.

<!-- _layouts/post.html -->
<!DOCTYPE html>
<html>
  <head>
    <title>Jekyll Basic 2</title>
  </head>
  <body>
    <article>
      <h1>Jekyll Basic 2</h1>
      <div class="content">
        <article class="post">
    <header class="post-header">
        <h1 class="post-title">Jekyll Basic</h1>
        <div class="post-meta">
            <time class="post-date">2025년 09월 01일</time>
            
            <div class="post-categories">
                
                    
                    <span class="category-tag">Tools</span>
                    
                
                    
                
                
                <span class="subcategory-tag">github-blog</span>
                
            </div>
            
            
            <div class="post-tags">
                
                <span class="tag">#jekyll</span>
                
                <span class="tag">#github_pages</span>
                
                <span class="tag">#study-bloging</span>
                
            </div>
            
        </div>
    </header>

    <div class="post-content">
        <p>작년에 처음 jekyll 블로그를 만들어 보았는데요.. css고 자바스크립트고 아무것도 모르겠으니 그냥 귀엽게 만든 분의 레포지토리를 클론해서 사용했습니다. 그래서 그냥 이것저것 gpt에게 던져주면서 누덕누덕 기워서 만들었는데, 이렇게 만들다보니 제대로 이해하지 못해서 구현하고 싶은 부분은 만들지 못하고 넘어갔습니다.
이번에는 차근차근 공부하면서 나만의 블로그를 제대로 구축해보려고 합니다!!</p>

<p>이번 포스트에서는 jekyll이 무엇인지, Github Pages와 어떤 관계인지, 그리고 기본적인 프로젝트 구조는 어떻게 구성되어있는지 알아보겠습니다.</p>

<h1 id="소개">소개</h1>

<h2 id="jekyll이란-무엇인가">jekyll이란 무엇인가?</h2>

<p>jekyll은 <strong>정적 사이트 생성기</strong>입니다. 마크다운 파일과 HTML 파일을 사용해서 정적 웹사이트를 생성해줍니다.</p>

<p>_config.yml와 같은 설정 파일과 마크다운 파일을 읽어서 완성된 HTML 사이트를 생성합니다.</p>

<h2 id="github-pages와-무슨-관계인가">Github Pages와 무슨 관계인가?</h2>

<p>GitHub Pages는 GitHub에서 제공하는 무료 웹 호스팅 서비스입니다. Jekyll을 공식적으로 지원하기 때문에 마크다운 파일을 푸시하기만 하면 자동으로 빌드되어 웹사이트로 배포됩니다.</p>

<h3 id="github-pages--jekyll의-워크플로">GitHub Pages + Jekyll의 워크플로</h3>

<ol>
  <li><strong>로컬에서 마크다운 작성</strong> → 블로그 포스트 작성</li>
  <li><strong>GitHub 레포지토리에 푸시</strong> → <code class="language-plaintext highlighter-rouge">git push origin main</code></li>
  <li><strong>GitHub에서 자동 빌드</strong> → Jekyll이 HTML로 변환</li>
  <li><strong>웹사이트 자동 배포</strong> → <code class="language-plaintext highlighter-rouge">username.github.io</code>에서 확인 가능</li>
</ol>

<p>이 과정이 모두 자동화되어 있어서 글 작성에만 집중할 수 있다는 것이 가장 큰 장점입니다.</p>

<h1 id="프로젝트-구조-이해하기">프로젝트 구조 이해하기</h1>

<p>Jekyll 프로젝트의 기본 구조를 살펴보겠습니다:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>my-blog/
├── _config.yml          # 사이트 전체 설정
├── _posts/              # 블로그 포스트들
│   └── 2025-01-01-first-post.md
├── _layouts/            # HTML 템플릿들
│   ├── default.html
│   └── post.html
├── _includes/           # 재사용 가능한 HTML 조각들
│   ├── header.html
│   └── footer.html
├── _sass/               # SCSS 부분 파일들
│   ├── _base.scss
│   └── _layout.scss
├── assets/              # CSS, JS, 이미지 등
│   └── css/
│       └── style.scss
├── index.md             # 홈페이지
└── about.md             # 소개 페이지
</code></pre></div></div>

<h3 id="주요-폴더와-파일-역할">주요 폴더와 파일 역할</h3>

<p><strong><code class="language-plaintext highlighter-rouge">_config.yml</code></strong>: 사이트의 모든 설정을 관리하는 핵심 파일입니다. 사이트 제목, 설명, 플러그인, 테마 등을 여기서 설정합니다.</p>

<p><strong><code class="language-plaintext highlighter-rouge">_posts/</code></strong>: 블로그 포스트들이 저장되는 폴더입니다. 파일명은 반드시 <code class="language-plaintext highlighter-rouge">YYYY-MM-DD-title.md</code> 형식을 따라야 합니다.</p>

<p><strong><code class="language-plaintext highlighter-rouge">_layouts/</code></strong>: HTML 템플릿들이 저장되는 폴더입니다. 마크다운 파일들은 이 템플릿을 기반으로 완성된 HTML 페이지가 됩니다.</p>

<p><strong><code class="language-plaintext highlighter-rouge">_includes/</code></strong>: 여러 페이지에서 재사용할 수 있는 HTML 조각들을 저장합니다. 헤더, 푸터, 네비게이션 등을 모듈화할 수 있습니다.</p>

<h2 id="_configyml-필수-설정들">_config.yml 필수 설정들</h2>

<p>Jekyll 사이트의 핵심인 <code class="language-plaintext highlighter-rouge">_config.yml</code> 파일의 기본 설정을 알아보겠습니다:</p>

<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 사이트 기본 정보</span>
<span class="na">title</span><span class="pi">:</span> <span class="s">개발자 블로그</span>
<span class="na">email</span><span class="pi">:</span> <span class="s">your-email@example.com</span>
<span class="na">description</span><span class="pi">:</span> <span class="pi">&gt;-</span>
  <span class="s">Jekyll과 GitHub Pages로 만든 개발 블로그입니다.</span>
  <span class="s">프로그래밍과 기술에 대한 이야기를 나눕니다.</span>

<span class="c1"># 빌드 설정</span>
<span class="na">baseurl</span><span class="pi">:</span> <span class="s2">"</span><span class="s">"</span> <span class="c1"># 서브 디렉토리가 있다면 "/blog" 형식으로</span>
<span class="na">url</span><span class="pi">:</span> <span class="s2">"</span><span class="s">https://username.github.io"</span>

<span class="c1"># 마크다운 처리</span>
<span class="na">markdown</span><span class="pi">:</span> <span class="s">kramdown</span>
<span class="na">highlighter</span><span class="pi">:</span> <span class="s">rouge</span>

<span class="c1"># 플러그인</span>
<span class="na">plugins</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">jekyll-feed</span>
  <span class="pi">-</span> <span class="s">jekyll-sitemap</span>
  <span class="pi">-</span> <span class="s">jekyll-seo-tag</span>

<span class="c1"># 제외할 파일들</span>
<span class="na">exclude</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">Gemfile</span>
  <span class="pi">-</span> <span class="s">Gemfile.lock</span>
  <span class="pi">-</span> <span class="s">node_modules</span>
  <span class="pi">-</span> <span class="s">vendor</span>
</code></pre></div></div>

<p>이 설정들은 Jekyll이 사이트를 빌드할 때 어떻게 처리할지를 결정합니다. 특히 <code class="language-plaintext highlighter-rouge">baseurl</code>과 <code class="language-plaintext highlighter-rouge">url</code>은 링크 생성에 중요하므로 정확히 설정해야 합니다.</p>

<hr />

<p><strong>참고 자료</strong>:</p>

<ul>
  <li><a href="https://jekyllrb.com/docs/">Jekyll 공식 문서</a></li>
  <li><a href="https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll">GitHub Pages 문서</a></li>
</ul>

    </div>

    <footer class="post-footer">
        <div class="post-nav">
            
            <a class="prev-post" href="/development/alembic/">
                <span class="nav-label">이전 글</span>
                <span class="nav-title">SQLAlchemy와 Alembic으로 DB 관리하기</span>
            </a>
            
            
            
            <a class="next-post" href="/tools/jekyll-basic/">
                <span class="nav-label">다음 글</span>
                <span class="nav-title">Jekyll Basic 2</span>
            </a>
            
        </div>
        
        <div class="back-to-home">
            <a href="/">← 홈으로 돌아가기</a>
        </div>
    </footer>
</article>
        <!-- 마크다운 내용이 여기에! -->
      </div>
    </article>
  </body>
</html>

그러면 두 내용이 결합되어서 페이지가 렌더링 됩니다.

_layouts 폴더 구조와 활용

Jekyll에서 레이아웃 파일들은 _layouts/ 폴더에 저장됩니다. 저는 이런 구조로 만들었습니다.

_layouts/
├── default.html      # 기본 레이아웃 (모든 페이지의 베이스)
└── post.html         # 블로그 포스트용 레이아웃

defautl.html : 모든 페이지의 베이스가 되는 기본 레이아웃

이 기본 레이아웃은 모든 페이지에 공통으로 들어갈 헤더, 네비게이션, 푸터를 포함합니다.

레이아웃 상속과 계층 구조

Jekyll의 강력한 기능 중 하나는 레이아웃 상속입니다. 레이아웃이 다른 레이아웃을 상속받을 수 있어요.

post.html : default 레이아웃을 상속받아 만들어진 post 레이아웃

post.html 레이아웃은 default 레이아웃을 상속받아서 포스트 전용 구조를 만듭니다.

이렇게 하면 post.html의 내용이 default.html의 content 부분에 들어가게 됩니다.

Liquid 템플릿 언어 기초

Jekyll은 Liquid 템플릿 언어를 사용합니다. 이중 중괄호와 중괄호-퍼센트 문법을 통해 동적인 콘텐츠를 생성할 수 있어요.

주요 Liquid 문법

변수 출력:

  • page.title: 페이지 제목
  • site.title: 사이트 제목
  • content: 페이지/포스트 내용

조건문:

  • if 조건문으로 조건부 렌더링
  • unless 조건문으로 반대 조건 처리

반복문:

  • for 반복문으로 목록 처리
  • 포스트 목록이나 카테고리 목록 순회

필터 활용:

  • date: 날짜 포맷팅
  • strip_html: HTML 태그 제거
  • truncate: 텍스트 자르기
  • relative_url: 상대 URL 생성

페이지별 레이아웃 지정하기

마크다운 파일의 Front Matter에서 사용할 레이아웃을 지정합니다:

홈페이지는 layout: home을 사용하여 홈 레이아웃을 적용합니다.

포스트는 layout: post를 사용하여 포스트 레이아웃을 적용합니다.

소개 페이지는 layout: page를 사용하여 기본 페이지 레이아웃을 적용합니다.

실제 활용 예제

실제로 홈페이지에 섹션을 나누어 구성해보겠습니다:

home.html 레이아웃은 홈페이지 전용으로 히어로 섹션과 최신 포스트 목록을 포함합니다.

이렇게 구성하면 index.md에서 layout: home을 지정했을 때 위의 구조로 페이지가 생성됩니다.

참고 자료: