Gatsby 블로그 스킨 커스터마이징 — 나만의 디자인 만들기

안녕하세요, 자바파커입니다.

지난 포스팅에서 Gatsby 블로그를 설치하고 배포까지 마쳤습니다. 하지만 기본 테마 그대로 사용하기에는 아쉬운 부분이 있습니다. 이번 포스팅에서는 gatsby-starter-hoodie 테마를 기준으로 블로그 디자인을 나만의 스타일로 커스터마이징하는 방법을 알아보겠습니다.

Gatsby 테마 구조 이해

커스터마이징을 시작하기 전에 테마의 폴더 구조를 이해하는 것이 중요합니다.

src/
├── assets/
│   └── theme/
│       └── index.js        # 테마 색상, 크기 등 핵심 설정
├── components/
│   ├── Article/            # 본문 영역 컴포넌트
│   ├── Bio/                # 프로필 영역
│   ├── Header/             # 상단 헤더
│   ├── Layout/             # 전체 레이아웃
│   ├── Sidebar/            # 사이드바
│   └── ...
├── pages/
│   └── index.js            # 메인 페이지
└── templates/
    └── Post.js             # 개별 포스트 템플릿

핵심 파일은 src/assets/theme/index.js입니다. 이 파일에서 색상, 크기, 폰트 등 대부분의 디자인 변수를 관리합니다.

콘텐츠 폭 조정

기본 테마의 콘텐츠 폭이 좁게 느껴진다면 조정할 수 있습니다.

Layout/Body 컴포넌트 수정

src/components/Layout/Body/index.js 파일을 찾아 max-width 값을 변경합니다.

// src/components/Layout/Body/index.js
import styled from "styled-components"

const Body = styled.div`
  margin: 0 auto;
  padding-top: 80px;
  max-width: 680px;  /* 기본값 */

  @media (max-width: 768px) {
    padding: 80px 16px 0;
  }
`

이 값을 필요에 따라 조정합니다.

const Body = styled.div`
  margin: 0 auto;
  padding-top: 80px;
  max-width: 760px;  /* 더 넓은 콘텐츠 영역 */

  @media (max-width: 768px) {
    padding: 80px 20px 0;
  }
`

팁: 너무 넓으면 한 줄에 글자 수가 많아져 가독성이 떨어집니다. 일반적으로 680px~800px 사이가 적당합니다.

테마 변수로 관리하기

반복 사용되는 값은 테마 변수로 관리하면 유지보수가 편리합니다.

// src/assets/theme/index.js 에 추가
const size = {
  maxWidth: "760px",
  mobileBreakpoint: "768px",
  tabletBreakpoint: "1024px",
}

export { size }

타이포그래피 변경

블로그의 분위기를 결정짓는 가장 큰 요소는 폰트입니다.

웹 폰트 추가

Google Fonts나 눈누(Noonnu)에서 원하는 폰트를 선택합니다. gatsby-browser.js에서 웹 폰트를 로드하는 방법이 가장 간단합니다.

// gatsby-browser.js
import "./src/assets/fonts/fonts.css"

/* src/assets/fonts/fonts.css */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;500;700&display=swap');
@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap');

폰트 적용

전역 스타일 또는 테마 파일에서 폰트를 적용합니다.

// src/assets/theme/index.js
const fonts = {
  body: "'Noto Sans KR', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
  code: "'JetBrains Mono', 'Fira Code', Consolas, monospace",
}

export { fonts }

styled-components에서 사용할 때는 다음과 같이 적용합니다.

import { fonts } from "../../assets/theme"

const Content = styled.div`
  font-family: ${fonts.body};
  font-size: 16px;
  line-height: 1.8;
  letter-spacing: -0.01em;
  word-break: keep-all;
`

글꼴 크기와 행간 조정

가독성을 높이려면 line-height(행간)와 letter-spacing(자간) 조정이 중요합니다.

/* 추천 설정 */
body {
  font-size: 16px;        /* 본문 기본 크기 */
  line-height: 1.8;       /* 행간: 1.6~1.8 추천 */
  letter-spacing: -0.01em; /* 한글은 약간 좁히면 자연스럽습니다 */
  word-break: keep-all;   /* 한글 단어 단위 줄바꿈 */
}

h1 { font-size: 2rem; font-weight: 700; }
h2 { font-size: 1.5rem; font-weight: 700; }
h3 { font-size: 1.25rem; font-weight: 500; }

다크/라이트 테마 색상 커스터마이징

gatsby-starter-hoodie는 다크모드를 기본 지원합니다. 색상 설정은 테마 파일에서 관리합니다.

theme/index.js 수정

// src/assets/theme/index.js

const light = {
  // 배경 색상
  bodyBackground: "#ffffff",
  cardBackground: "#f8f9fa",

  // 텍스트 색상
  text: "#1a1a2e",
  textSecondary: "#6c757d",
  textTertiary: "#adb5bd",

  // 강조 색상
  primary: "#0066cc",
  primaryLight: "#e7f1ff",

  // 경계선
  border: "#e9ecef",
  borderLight: "#f1f3f5",

  // 인라인 코드
  inlineCodeBackground: "#f1f3f5",
  inlineCodeText: "#e74c3c",

  // 헤더
  headerBackground: "rgba(255, 255, 255, 0.85)",
}

const dark = {
  // 배경 색상
  bodyBackground: "#1a1a2e",
  cardBackground: "#16213e",

  // 텍스트 색상
  text: "#e0e0e0",
  textSecondary: "#a0a0a0",
  textTertiary: "#707070",

  // 강조 색상
  primary: "#4dabf7",
  primaryLight: "#1a2744",

  // 경계선
  border: "#2c3e50",
  borderLight: "#233554",

  // 인라인 코드
  inlineCodeBackground: "#2d2d2d",
  inlineCodeText: "#ff6b6b",

  // 헤더
  headerBackground: "rgba(26, 26, 46, 0.85)",
}

export { light, dark }

색상 팔레트 선택 팁

배경색: 순백(#fff)보다 살짝 톤을 줄인 #fafafa나 #f8f9fa가 눈에 편합니다.
다크모드 배경: 순검정(#000)보다 짙은 남색(#1a1a2e)이나 짙은 회색(#1e1e1e)이 부드럽습니다.
강조색(primary): 블로그의 정체성을 나타내는 색상을 하나 정해서 일관되게 사용합니다.
대비: 텍스트와 배경의 명암비가 최소 4.5:1 이상이 되어야 가독성이 보장됩니다. WebAIM Contrast Checker에서 확인할 수 있습니다.

코드 블록 스타일링

기술 블로그에서 코드 블록은 매우 중요한 요소입니다. Gatsby는 기본적으로 Prism.js를 사용합니다.

Prism.js 테마 변경

gatsby-starter-hoodie에서 사용하는 Prism 테마를 변경하려면 gatsby-browser.js에서 import를 수정합니다.

// gatsby-browser.js

// 기본 테마 대신 원하는 테마를 import합니다
// import "prismjs/themes/prism.css"           // 라이트
// import "prismjs/themes/prism-tomorrow.css"  // 다크
// import "prismjs/themes/prism-okaidia.css"   // Monokai 스타일
import "prismjs/themes/prism-vsc-dark-plus.css" // VS Code 스타일

커스텀 코드 블록 스타일

Prism 테마를 직접 오버라이드하면 더 세밀하게 조정할 수 있습니다.

/* src/assets/styles/code.css */

/* 코드 블록 컨테이너 */
.gatsby-highlight {
  margin: 1.5em 0;
  border-radius: 8px;
  overflow: hidden;
}

/* 코드 블록 본문 */
.gatsby-highlight pre[class*="language-"] {
  background: #1e1e2e;
  padding: 1.2em;
  border-radius: 8px;
  font-size: 14px;
  line-height: 1.6;
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
}

/* 인라인 코드 */
:not(pre) > code[class*="language-"] {
  background: var(--inline-code-bg, #f1f3f5);
  color: var(--inline-code-text, #e74c3c);
  padding: 0.15em 0.4em;
  border-radius: 4px;
  font-size: 0.9em;
}

/* 코드 블록 언어 표시 */
.gatsby-highlight pre[class*="language-"]::before {
  content: attr(class);
  position: absolute;
  top: 0;
  right: 0;
  padding: 2px 8px;
  font-size: 11px;
  color: #999;
  text-transform: uppercase;
}

코드 복사 버튼 추가

코드 블록에 복사 버튼을 추가하면 사용자 경험이 크게 향상됩니다. gatsby-remark-code-buttons 플러그인을 사용합니다.

npm install gatsby-remark-code-buttons

gatsby-config.js에 플러그인을 추가합니다.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: "gatsby-transformer-remark",
      options: {
        plugins: [
          {
            resolve: "gatsby-remark-code-buttons",
            options: {
              buttonText: "복사",
              toasterText: "복사되었습니다!",
              toasterDuration: 2000,
            },
          },
          // ... 기존 플러그인들
        ],
      },
    },
  ],
}

복사 버튼의 스타일도 추가합니다.

/* 코드 복사 버튼 스타일 */
.gatsby-code-button-container {
  position: relative;
}

.gatsby-code-button {
  position: absolute;
  top: 8px;
  right: 8px;
  background: rgba(255, 255, 255, 0.1);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 4px;
  padding: 4px 10px;
  color: #ccc;
  font-size: 12px;
  cursor: pointer;
  transition: all 0.2s ease;
  z-index: 1;
}

.gatsby-code-button:hover {
  background: rgba(255, 255, 255, 0.2);
  color: #fff;
}

헤더/푸터 커스터마이징

헤더 수정

헤더는 블로그의 첫인상을 결정합니다. src/components/Header/index.js를 수정합니다.

// src/components/Header/index.js
import React from "react"
import styled from "styled-components"

const HeaderWrapper = styled.header`
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 56px;
  background: ${props => props.theme.headerBackground};
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border-bottom: 1px solid ${props => props.theme.border};
  z-index: 100;
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 0 24px;
  transition: background 0.3s ease;
`

const Logo = styled.a`
  font-size: 1.2rem;
  font-weight: 700;
  color: ${props => props.theme.text};
  text-decoration: none;

  &:hover {
    color: ${props => props.theme.primary};
  }
`

팁: backdrop-filter: blur()를 사용하면 스크롤할 때 배경이 흐려지는 글래스모피즘 효과를 줄 수 있습니다.

푸터 추가

gatsby-starter-hoodie에는 기본 푸터가 간단하게 되어 있습니다. 커스텀 푸터를 추가해 봅시다.

// src/components/Footer/index.js
import React from "react"
import styled from "styled-components"

const FooterWrapper = styled.footer`
  margin-top: 80px;
  padding: 40px 0;
  border-top: 1px solid ${props => props.theme.border};
  text-align: center;
  font-size: 0.85rem;
  color: ${props => props.theme.textSecondary};
`

const Footer = () => (
  <FooterWrapper>
    <p>
      &copy; {new Date().getFullYear()} AI JAVAPARK. Built with{" "}
      <a href="https://www.gatsbyjs.com/" target="_blank" rel="noreferrer">
        Gatsby
      </a>
    </p>
  </FooterWrapper>
)

export default Footer

반응형 브레이크포인트 조정

다양한 디바이스에서 최적의 경험을 제공하기 위해 반응형 디자인을 조정합니다.

미디어 쿼리 정리

일관된 미디어 쿼리를 사용하기 위해 브레이크포인트를 정의합니다.

// src/assets/theme/breakpoints.js
const breakpoints = {
  mobile: "576px",
  tablet: "768px",
  desktop: "1024px",
  wide: "1200px",
}

const media = {
  mobile: `@media (max-width: ${breakpoints.mobile})`,
  tablet: `@media (max-width: ${breakpoints.tablet})`,
  desktop: `@media (max-width: ${breakpoints.desktop})`,
  wide: `@media (min-width: ${breakpoints.wide})`,
}

export { breakpoints, media }

styled-components에서 활용

import { media } from "../../assets/theme/breakpoints"

const Container = styled.div`
  max-width: 760px;
  margin: 0 auto;
  padding: 0 24px;

  ${media.tablet} {
    padding: 0 20px;
  }

  ${media.mobile} {
    padding: 0 16px;
  }
`

모바일 최적화 체크리스트

반응형 커스터마이징 시 다음 항목들을 꼭 확인합니다.

모바일에서 텍스트가 잘리지 않는지 확인
코드 블록이 가로 스크롤로 처리되는지 확인
이미지가 컨테이너 폭을 넘지 않는지 확인
터치 타겟(버튼, 링크)이 최소 44px 이상인지 확인
헤더가 모바일에서 적절히 축소되는지 확인

크롬 개발자 도구(F12)의 디바이스 툴바를 활용하면 다양한 화면 크기를 쉽게 테스트할 수 있습니다.

변경사항 적용 및 배포

모든 커스터마이징을 마쳤다면 개발 서버에서 결과를 확인하고 배포합니다.

# 개발 서버에서 확인
gatsby develop

# 문제가 없다면 배포
npm run deploy

주의: gatsby develop에서는 보이지 않는 문제가 gatsby build에서 발생할 수 있습니다. 배포 전에 반드시 gatsby build로 프로덕션 빌드를 테스트하세요.

자주 묻는 질문 (FAQ)

Q1. styled-components를 몰라도 커스터마이징할 수 있나요?

네, 기본 CSS 문법만 알면 됩니다. styled-components는 JavaScript 파일 안에 CSS를 작성하는 방식일 뿐, 문법 자체는 CSS와 동일합니다. 백틱(`) 안에 일반 CSS를 그대로 작성하면 됩니다. 다만 ${} 구문으로 JavaScript 변수를 활용할 수 있다는 점이 일반 CSS와 다릅니다.

Q2. 테마 수정 후 기존 글 스타일이 깨지는 경우 어떻게 하나요?

gatsby clean 명령어로 캐시를 초기화한 뒤 다시 빌드해 보세요. 대부분의 스타일 관련 이슈는 캐시 문제입니다.

gatsby clean && gatsby develop

그래도 문제가 지속된다면 브라우저 개발자 도구에서 해당 요소를 검사하여 어떤 스타일이 적용되고 있는지 확인합니다.

Q3. 다크모드 전환이 깜빡이는 현상이 있습니다.

SSR(서버 사이드 렌더링) 시점과 클라이언트 사이드 렌더링 시점의 테마가 다르면 깜빡임이 발생합니다. gatsby-ssr.js에서 초기 테마를 설정하는 스크립트를 <body> 태그 앞에 삽입하면 해결됩니다.

// gatsby-ssr.js
export const onRenderBody = ({ setPreBodyComponents }) => {
  setPreBodyComponents([
    <script
      key="theme-script"
      dangerouslySetInnerHTML={{
        __html: `
          (function() {
            try {
              var mode = localStorage.getItem('theme');
              if (mode) {
                document.body.className = mode;
              }
            } catch (e) {}
          })();
        `,
      }}
    />,
  ])
}

다음 포스팅에서는 마크다운 글쓰기와 카테고리 관리 방법을 다룹니다. frontmatter 작성법, 태그 전략, 시리즈 기능, 폴더 구조 설계까지 체계적인 블로그 운영법을 알아보겠습니다.