4 minute read

Jekyll(Minimal Mistakes) 기반 개인 블로그 제작 회고

1. 시작하며

  • Jekyll과 Minimal Mistakes 테마로 블로그를 시작했습니다.
  • 단순히 글을 올리는 공간이 아니라, 나만의 색상, UX, 기능을 갖춘 블로그를 만들고자 했습니다.
  • 오픈소스 테마의 구조를 분석하고, 원하는 대로 커스터마이징하는 과정에서 Jekyll의 빌드 구조와 Liquid 문법, SCSS, JS의 상호작용을 깊이 이해하게 됐습니다.
  • 블로그를 직접 운영하며, 실사용자 입장에서 필요한 기능과 디자인을 고민하게 됐습니다.

2. 테마 커스터마이징

  • _custom.scss에서 CSS 변수로 다크/라이트 테마 색상을 일괄적으로 관리했습니다. 주요 색상, 배경, 텍스트, 포인트 컬러, 카드/코드/버튼/네비게이션 등 모든 UI 요소를 변수로 통일해 유지보수성을 높였습니다.
// _sass/minimal-mistakes/_custom.scss
body[data-theme="dark"] {
  --bg-primary: #0f0f1a;
  --accent-primary: #a855f7;
  --text-primary: #ffffff;
  ...
}
body[data-theme="light"] {
  --bg-primary: #fff;
  --accent-primary: #7c3aed;
  --text-primary: #1a1a1a;
  ...
}
  • masthead, greedy-nav, 푸터, sidebar 등 주요 UI를 테마에 맞게 세밀하게 조정했습니다. 예를 들어, 네비게이션과 푸터의 배경/글자색, hover 효과, border-radius, box-shadow 등도 테마별로 다르게 적용했습니다.
// _sass/minimal-mistakes/_custom.scss
.masthead {
  background: color-mix(in srgb, var(--bg-primary) 95%, transparent);
  border-bottom: 1.5px solid var(--border-color);
  ...
}
.greedy-nav a, .masthead__menu a {
  color: var(--text-primary);
  border-radius: 8px;
  transition: all 0.2s ease;
}
  • skip navigation, 불필요한 마크업, 중복 padding/margin 등은 과감히 제거해 코드와 UI를 간결하게 만들었습니다.
  • 테마 토글 버튼을 masthead.html과 custom.js에서 구현하여, body에 data-theme 속성을 동적으로 적용했습니다. 토글 버튼은 Search 메뉴 옆에 고정시켜 접근성을 높였습니다.
<!-- _includes/masthead.html (일부) -->

// assets/js/custom.js (일부)
document.addEventListener('DOMContentLoaded', function () {
  const themeToggle = document.querySelector('#darkLightToggle');
  function applyTheme(theme) {
    document.body.setAttribute('data-theme', theme);
    ...
  }
  const savedTheme = localStorage.getItem('theme');
  if (savedTheme) {
    applyTheme(savedTheme);
  } else {
    applyTheme('dark');
  }
  if (themeToggle) {
    themeToggle.addEventListener('click', function() {
      const current = document.body.getAttribute('data-theme');
      const next = current === 'light' ? 'dark' : 'light';
      applyTheme(next);
      localStorage.setItem('theme', next);
    });
  }
});
  • 반응형 디자인도 신경써서, 모바일 환경에서 sidebar, 카드, 네비게이션, 테마 토글 버튼의 위치와 크기를 최적화했습니다.

3. 검색 기능 개선

  • 기존 Lunr 기반 검색에서 Google CSE로도 전환할 수 있도록 구조를 파악하고 설정했습니다. _config.yml에서 search_provider를 쉽게 바꿀 수 있도록 했고, 실제로 Algolia, Lunr, Google CSE 등 다양한 검색 엔진을 실험했습니다.
# _config.yml (일부)
search: true
search_provider: algolia # lunr, algolia, google_cse 등
  • 검색창을 상단 고정, 오버레이, 네비게이션 토글 등 다양한 방식으로 시도했습니다. 특히, 네비게이션의 “Search” 메뉴 클릭 시 오버레이 검색창이 뜨도록 JS/HTML 구조를 변경해 UX를 개선했습니다.
// assets/js/custom.js (일부)
var navSearch = document.querySelector('.nav-search-link');
var overlay = document.getElementById('searchOverlay');
if (navSearch && overlay) {
  navSearch.addEventListener('click', function(e) {
    e.preventDefault();
    overlay.classList.add('active');
    ...
  });
}
  • 검색 결과는 카드형 UI로, 다크/라이트 테마 모두 자연스럽게 적용되도록 했습니다. 검색 결과가 많을 때도 가독성을 해치지 않도록 카드 배경, 텍스트, 하이라이트 색상을 테마 변수로 통일했습니다.
// _sass/minimal-mistakes/_custom.scss
.card {
  background: var(--card-bg);
  color: var(--text-primary);
  border-radius: 18px;
  ...
}

4. 댓글/리액션/Disqus 다크모드 연동

  • Disqus(디스커스) 댓글 영역이 iframe이라 SCSS로 직접 커스텀할 수 없었습니다. 대신, JS에서 사이트의 data-theme을 감지해 Disqus에 postMessage로 테마를 전달하도록 구현했습니다.
<!-- _includes/comments-providers/disqus.html (일부) -->
<script>
  var disqus_config = function () {
    this.callbacks.onReady = [function() {
      var theme = document.body.getAttribute('data-theme') || 'light';
      var iframe = document.getElementById('disqus_thread')?.querySelector('iframe');
      if (iframe) {
        iframe.contentWindow.postMessage({
          type: 'set-theme',
          theme: theme
        }, 'https://disqus.com');
      }
    }];
  };
  var observer = new MutationObserver(function() {
    var theme = document.body.getAttribute('data-theme') || 'light';
    updateDisqusTheme(theme);
  });
  observer.observe(document.body, { attributes: true, attributeFilter: ['data-theme'] });
</script>
  • 테마 토글 시에도 MutationObserver로 자동 동기화되도록 했습니다. 즉, 사용자가 다크/라이트 테마를 바꿀 때마다 댓글 영역도 즉시 테마가 맞춰집니다.
  • 리액션, 정렬, 공유 등 모든 텍스트/아이콘이 테마에 맞게 바뀌도록 했습니다. 댓글 영역 외에도, 공유 버튼, 리액션 아이콘 등도 테마별로 색상과 hover 효과를 다르게 적용했습니다.
  • 댓글 기능은 _config.yml에서 provider만 바꾸면 Disqus, Giscus, Utterances 등 다양한 서비스로 쉽게 전환할 수 있도록 구조화했습니다.

5. 코드/디자인 세부 개선

  • 코드블록 스타일에서 border, radius, box-shadow 등 불필요한 부분을 제거하고, 색상 변수를 통일했습니다. 코드블록, 인라인 코드, pre 태그 모두 다크/라이트에 맞는 배경과 글자색, border, radius를 적용했습니다.
// _sass/minimal-mistakes/_custom.scss
.highlight, pre, code {
  background: var(--code-bg) !important;
  color: var(--code-text) !important;
  font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', monospace;
  ...
}
code:not(pre code) {
  background: var(--hover-bg) !important;
  color: var(--accent-primary) !important;
  padding: 3px 8px;
  border-radius: 6px;
  border: 1px solid var(--border-color);
}
  • sidebar, pagination, meta, share, comments 등 모든 컴포넌트의 색상, 간격, hover 효과를 테마에 맞게 반복적으로 개선했습니다. 예를 들어, pagination의 현재 페이지, hover, disabled 상태까지 모두 변수로 관리했습니다.
// _sass/minimal-mistakes/_custom.scss
.pagination li a {
  background: transparent;
  color: var(--text-secondary);
  border: 1px solid var(--border-color);
  border-radius: 8px;
  ...
}
.pagination li a:hover {
  background: var(--accent-primary);
  color: var(--pagination-hover-text);
}
  • 404, about, 각종 archive 페이지 등도 세부적으로 다듬었습니다. 각 페이지의 배경, 카드, 타이틀, 링크, 버튼 등도 일관성 있게 커스터마이징했습니다.
  • 반응형 레이아웃, 스크롤바, selection, 링크 스타일 등도 세밀하게 조정해, 모바일/PC 어디서나 일관된 경험을 제공하도록 했습니다.

6. 시행착오 & 배운 점

  • JS/CSS 변수명 불일치로 테마 토글이 동작하지 않는 문제, body에 data-theme를 둘지 html에 둘지 고민하며 해결했습니다. 실제로 여러 번 변수명을 잘못 써서 테마가 적용되지 않는 버그를 겪었습니다.
  • 검색창 위치와 동작(상단 고정, 오버레이, 네비게이션 연동 등)을 여러 번 실험했습니다. 오버레이 방식이 UX에 가장 적합하다고 판단해 적용했습니다.
  • Disqus 등 외부 서비스와 다크모드 연동은 JS postMessage로 해결했습니다. iframe 구조의 한계와 postMessage의 활용법을 실전에서 익혔습니다.
  • 이미지 경로, 파일 위치, Jekyll의 baseurl/url 설정 등도 꼼꼼히 체크해야 했습니다. 특히, 커스텀 도메인이나 GitHub Pages에서 경로가 꼬이지 않도록 _config.yml의 url/baseurl 세팅을 반복적으로 점검했습니다.
  • SCSS 변수, JS 로컬스토리지, MutationObserver 등 다양한 웹 기술을 실전에서 활용하며, 유지보수성과 확장성을 모두 고려하게 됐습니다.

7. 마치며

  • 단순히 테마만 바꾼 것이 아니라, 내가 원하는 UX/디자인/기능을 직접 구현하며 Jekyll 블로그에 대한 이해가 깊어졌습니다.
  • 시행착오를 겪으며 CSS/JS 구조, Jekyll의 동작 원리, 외부 서비스 연동까지 폭넓게 경험했습니다. 특히, 오픈소스 테마를 내 입맛대로 바꾸는 과정에서 웹 프론트엔드의 다양한 노하우를 쌓았습니다.
  • 앞으로도 새로운 기능과 디자인을 계속 실험하며 성장할 예정입니다. 예를 들어, 다국어 지원, 접근성 개선, SEO 최적화, 더 다양한 댓글/검색/공유 기능 등도 도전해보고 싶습니다.
  • 블로그 커스터마이징을 직접 해보면, 단순히 예쁜 테마를 고르는 것 이상의 실전 경험과 성장의 기회를 얻을 수 있습니다.

최종 결과:

  • 다크/라이트 테마를 완벽하게 지원했습니다. (body[data-theme], CSS 변수, JS 토글, 로컬스토리지, MutationObserver 등 활용)
  • 네비게이션, 푸터, 목차, 코드, 댓글, 검색 등 모든 UI/UX를 세밀하게 커스터마이징했습니다. (모든 컴포넌트의 색상/간격/hover/반응형까지 일관성 있게 적용)
  • 검색, 댓글, 리액션, 코드블록 등 실전에서 자주 쓰는 기능을 내 스타일로 완성했습니다. (검색 엔진 전환, 댓글 서비스 전환, 실시간 테마 동기화 등)

블로그 커스터마이징, 직접 해보면 정말 많이 배울 수 있습니다! 🚀

Leave a comment