Hugo 블로그 사용성 개선 가이드 - BlowFish 테마 커스터마이징과 프론트엔드 완성도 높이기

🎯 이 글에서 다루는 내용

#

이 가이드를 따라하면 Hugo BlowFish 테마 블로그의 사용성과 완성도를 완전히 업그레이드할 수 있습니다:

• ✅ 폴더 구조 정리 - 연도/월별로 깔끔하게 정리
• ✅ TOC 목차 활성화 - 균형잡힌 레이아웃 구성
• ✅ 코드 복사 버튼 - 개발자 친화적 기능 추가
• ✅ 댓글창 테마 동기화 - BlowFish 테마와 완벽 통합
• ✅ 고급 커스터마이징 - iframe 조작과 JavaScript 활용

예상 소요시간: 30분 | 난이도: 중급

😅 또 다른 개선의 시작…

#

안녕하세요! Hugo 블로그 구축기 8편으로 돌아온 CoderRed입니다!

7편에서 Invalid Token 지옥을 탈출한 후, 완성된 줄 알았던 블로그를 다시 보니… 뭔가 아쉬웠어요 😅

본문이 왼쪽으로 치우쳐 보이고, posts 폴더는 점점 지저분해지고, 댓글창 색깔은 따로 놀고…

“기능은 다 되는데 완성도가 좀…” 하는 느낌이었거든요.

그래서 오늘은 블로그 프론트엔드의 완성도를 한 단계 높이는 작업을 했습니다! 결과부터 말씀드리면… 정말 많이 좋아졌어요! 🎉

🗂️ 1단계: 폴더 구조 대정리

#

문제 상황

#

content/posts/
├── hugo-blog-complete-guide/
├── hugo-blog-troubleshooting/
├── hugo-blog-github-actions/
├── hugo-blog-google-analytics/
├── hugo-blog-telegram-notification/
├── hugo-blog-invalid-token-hell/
├── laptop-ssd-upgrade-guide/
└── ... (계속 늘어남)

포스트가 늘어날수록 posts 폴더가 점점 지저분해지고 있었어요!

해결책 고민

#

여러 방법을 고려해봤어요:

방법 1: 카테고리별 분류

content/posts/개발도구/
content/posts/일반/
content/posts/프로젝트/

방법 2: 연도/월별 분류 ⭐

content/posts/2025/09/
content/posts/2025/10/
content/posts/2026/01/

왜 연도/월별을 선택했나?

#

카테고리별 분류를 고려했는데, 카테고리가 몇 개 안 되면 결국 그 안에서 또 폴더가 왕창 늘어날 것 같더라고요 😅

연도/월별이 훨씬 깔끔한 이유:

• ✅ 각 월별로 적당한 분량 (월 3-5개 포스트 정도)
• ✅ 시간 순서대로 정리됨 (블로그 성장 과정도 보임)
• ✅ “언제 쓴 글이었지?” 찾기 쉬움
• ✅ URL도 의미있음 (/posts/2025/09/post-name/)

IntelliJ로 깔끔하게 이동

#

콘솔 명령어 대신 IntelliJ GUI로 작업했어요:

1. Project 탭에서 새 폴더 생성: 2025/09
2. 드래그 앤 드롭으로 기존 포스트들 이동
3. 실수해도 Ctrl+Z로 바로 되돌리기

정말 직관적이고 안전했어요!

결과

#

새로운 URL 구조:

https://coderred.com/posts/2025/09/hugo-blog-complete-guide/
https://coderred.com/posts/2025/09/hugo-blog-troubleshooting/

aliases는 과감히 포기! 아직 블로그 초기라 기존 링크가 많지 않아서 깔끔하게 갔습니다.

🧭 2단계: TOC 활성화로 레이아웃 개선

#

문제 발견

#

처음 스크린샷을 보니 본문이 왼쪽으로 치우쳐 있었어요. 오른쪽에 뭔가 나와야 할 것 같은데…

원인 파악

#

config/_default/params.toml을 확인해보니:

1
2

[article]
  showTableOfContents = false  # 이게 문제!

TOC(Table of Contents)가 꺼져 있어서 오른쪽 사이드바가 비어있던 거였어요!

해결

#

1
2

[article]
  showTableOfContents = true   # 활성화!

결과: 이제 오른쪽에 목차가 나타나면서 레이아웃이 균형잡혀 보여요!

🍞 브레드크럼은 과감히 포기

#

브레드크럼이 뭐야?

#

사이트에서 현재 위치를 보여주는 경로 표시예요:

홈 > posts > 2025 > 09 > Hugo 블로그 구축기 8편

왜 포기했나?

#

연도/월별 구조에서 브레드크럼이 나온다면 “2025”, “09” 이런 걸 클릭해봤자 별로 의미가 없더라고요 😅

대신 태그 시스템이 훨씬 유용해요:

• 개발도구 → 개발 관련 글들
• Hugo → Hugo 관련 글들
• 트러블슈팅 → 문제 해결 글들

최종 설정

#

1
2

[article]
  showBreadcrumbs = false  # 불필요하니까 끄기

📋 3단계: 코드 복사 버튼 추가

#

발견한 기능

#

TOML 파일을 살펴보다가 흥미로운 옵션을 발견했어요:

1

enableCodeCopy = true

코드 블록에 복사 버튼을 추가해주는 기능이었어요! 📋

왜 필요한가?

#

CoderRed 블로그에는 기술 콘텐츠가 많아서 이 기능이 완벽했어요:

1
2
3
4
5

# 이런 긴 Docker 명령어들...
docker run -d --name cusdis --restart unless-stopped --network npm_default -p 3000:3000...

# Git 명령어들...
hugo new posts/2025/09/new-post/index.md

복사 버튼 없으면 독자들이 드래그해서 복사해야 하는데, 복사 버튼 있으면 클릭 한 번이면 끝!

설정의 특이점

#

흥미롭게도 BlowFish 테마에서는:

• enableCodeCopy: params.toml에 설정
• lineNos (줄 번호): markup.toml에 설정

기능별로 파일이 분리되어 있어서 처음엔 헷갈렸지만, 찾고 나니 깔끔하더라고요!

1
2
3
4

# markup.toml
[highlight]
  lineNos = true
  lineNumbersInTable = true

🎨 4단계: 댓글창 색상의 대삽질

#

문제 상황

#

Cusdis 댓글 시스템이 잘 작동하는데… 색깔이 따로 놀고 있었어요 😤

• 다크모드: 블로그는 진한 네이비인데 댓글은 밝은 회색
• 라이트모드: 전체적으로는 괜찮았지만 미묘하게 안 맞음

첫 번째 시도: data-theme 조정

#

1
2
3
4
5

<!-- 처음 시도 -->
data-theme="dark"  <!-- 완전 까매져서 오히려 이상 -->

<!-- 두 번째 시도 -->
data-theme="auto"  <!-- 괜찮지만 완벽하지 않음 -->

두 번째 시도: CSS 필터

#

1
2
3
4
5

@media (prefers-color-scheme: dark) {
  #cusdis_thread iframe {
    filter: brightness(0.85) contrast(0.95) saturate(0.9) !important;
  }
}

필터로는 전체적인 밝기만 조정되어서 한계가 있었어요.

세 번째 시도: JavaScript로 iframe 내부 조작

#

이때 깨달았어요. 기존에 iframe 높이 조정하는 스크립트가 있었잖아요!

1
2

// 이미 이런 코드가 있었음
const iframeDoc = iframe.contentDocument || iframe.contentWindow.document;

이미 iframe 내부에 접근하고 있다면 색상도 바꿀 수 있지 않을까?

🎯 5단계: BlowFish 테마 감지 시스템 구축

#

핵심 아이디어

#

Cusdis가 BlowFish 테마 변경을 따라가게 하자!

테마 감지 로직

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

function getBlowfishTheme() {
    // 1. HTML/Body 클래스 확인
    const html = document.documentElement;
    const body = document.body;
    
    if (html.classList.contains('dark') || body.classList.contains('dark')) {
        return 'dark';
    }
    
    // 2. localStorage 확인
    const savedTheme = localStorage.getItem('blowfish-theme');
    if (savedTheme) {
        return savedTheme;
    }
    
    // 3. CSS 배경색으로 판단
    const bodyBg = getComputedStyle(document.body).backgroundColor;
    if (bodyBg.includes('rgb(')) {
        const rgb = bodyBg.match(/\d+/g);
        const brightness = (parseInt(rgb[0]) + parseInt(rgb[1]) + parseInt(rgb[2])) / 3;
        return brightness < 128 ? 'dark' : 'light';
    }
    
    // 4. 시스템 설정 확인
    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}

동적 스타일 적용

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

if (currentTheme === 'dark') {
    style.textContent = `
        * { color: #e2e8f0 !important; }
        body { background-color: #1e293b !important; }
        input, textarea { 
            background-color: #374151 !important; 
            color: #f3f4f6 !important;
        }
    `;
    console.log('✅ BlowFish 다크모드 → Cusdis 다크모드 적용');
} else {
    style.textContent = `
        * { color: #1f2937 !important; }
        body { background-color: #ffffff !important; }
        input, textarea { 
            background-color: #f9fafb !important; 
            color: #111827 !important;
        }
    `;
    console.log('✅ BlowFish 라이트모드 → Cusdis 라이트모드 적용');
}

실시간 테마 변경 감지

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 테마 변경 감지
const themeObserver = new MutationObserver(() => {
    setTimeout(adjustIframeHeight, 100); // 테마 변경 후 재적용
});

// HTML과 body의 클래스/속성 변경 감지
themeObserver.observe(document.documentElement, { 
    attributes: true, 
    attributeFilter: ['class', 'data-theme'] 
});

결과: 이제 BlowFish 테마를 변경하면 댓글창도 자동으로 따라 변경됩니다! 🎉

🔘 6단계: 버튼 디자인 세밀 조정

#

Comment/Reply 버튼 구조 파악

#

브라우저 개발자 도구로 실제 HTML을 확인해보니:

1
2
3
4
5
6
7

<!-- Comment 버튼 -->
<button class="text-sm bg-gray-200 p-2 px-4 font-bold dark:bg-transparent dark:border dark:border-gray-100">
  Comment
</button>

<!-- Reply 버튼 -->
<button type="button">Reply</button>

Cusdis는 Tailwind CSS 클래스를 사용하고 있었어요!

버튼별 차별화 스타일링

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

/* Comment 버튼 (주요 액션) */
button.font-bold {
    background-color: #2563eb !important;
    color: white !important;
    border: 1px solid #1d4ed8 !important;
    border-radius: 6px !important;
    padding: 8px 16px !important;
}

/* Reply 버튼 (보조 액션) */
button[type="button"] {
    background-color: #475569 !important;
    color: #e2e8f0 !important;
    border: 1px solid #64748b !important;
    border-radius: 6px !important;
    padding: 6px 12px !important;
}

디자인 컨셉:

• Comment 버튼: 주요 액션이라 파란색으로 눈에 띄게
• Reply 버튼: 보조 액션이라 회색 계열로 차분하게

🎉 최종 결과

#

달성한 성과들

#

• ✅ 깔끔한 연도/월별 폴더 구조
• ✅ TOC로 균형잡힌 레이아웃
• ✅ 코드 복사 버튼으로 사용성 개선
• ✅ BlowFish 테마와 완벽 동기화되는 댓글창
• ✅ 차별화된 버튼 디자인

통합 스크립트의 완성

#

기존의 iframe 높이 조정 스크립트에 모든 기능을 통합했어요:

1. iframe 높이 자동 조정 (기존 기능)
2. BlowFish 테마 감지 (새 기능)
3. Cusdis 색상 동기화 (새 기능)
4. 테마 변경 실시간 감지 (새 기능)
5. 버튼 스타일링 (새 기능)

모든 기능이 하나의 스크립트에서 매끄럽게 작동합니다!

💡 이번에 배운 것들

#

TOML 설정 파일의 구조

#

Hugo + BlowFish 테마에서는 기능별로 설정 파일이 분리되어 있어요:

config/_default/
├── config.toml      # 기본 Hugo 설정
├── params.toml      # 테마별 설정 (enableCodeCopy 등)
├── markup.toml      # 마크다운/코드 설정 (lineNos 등)
├── menus.toml       # 메뉴 설정
└── languages.toml   # 언어 설정

iframe 조작의 한계와 가능성

#

iframe 내부 조작은 CORS 정책 때문에 까다롭지만, 같은 주 도메인이면 가능한 경우가 많아요.

comments.coderred.com과 coderred.com이 같은 도메인이라 성공할 수 있었던 것 같아요!

CSS 선택자의 중요성

#

Cusdis처럼 외부 시스템을 커스터마이징할 때는 정확한 CSS 선택자가 핵심이에요:

1
2

button.font-bold      /* Tailwind 클래스 기반 */
button[type="button"] /* 속성 기반 */

브라우저 개발자 도구로 실제 HTML 구조를 파악하는 게 가장 중요했어요.

🚀 앞으로의 계획

#

블로그 시스템 완성도

#

이제 정말로 글쓰기에만 집중할 수 있는 환경이 완성됐어요:

• 📝 포스트 작성 → 📤 Git 푸시 → 🚀 자동 배포
• 💬 댓글 작성 → 📱 텔레그램 알림 → ⚡ 원클릭 승인
• 🌓 테마 변경 → 🎨 댓글창 자동 동기화

다음 확장 계획

#

• 검색 기능 활성화
• SEO 최적화 심화
• 광고 시스템 연동 (수익화!)
• 다국어 지원 확장

💬 마무리

#

정말 많은 걸 개선했는데, 가장 만족스러운 건 테마 변경 시 댓글창도 자동으로 따라 변하는 것이에요!

사용자들이 다크/라이트 모드를 전환할 때마다 모든 게 자연스럽게 어우러지니까 완성도가 정말 높아진 느낌이에요 😊

혹시 비슷한 작업을 하시다가 막히는 부분이 있으시면 댓글로 알려주세요! 특히 iframe 내부 스타일링이나 BlowFish 테마 커스터마이징 관련해서 도움이 될 수 있을 것 같아요.

다음 편에서는 정말로 기술 콘텐츠나 투자 이야기로 돌아올 예정입니다! 🚀

관련 포스트

#

• Hugo 블로그 구축 완전 가이드
• Hugo 댓글 시스템 구축하기
• Hugo Google Analytics 연동

Hugo 블로그 구축기 시리즈

#

1. 환경 설정부터 배포까지
2. 실제 겪은 문제들과 해결책
3. CI/CD 파이프라인 구축
4. Google Analytics 연동
5. 댓글 시스템 구축
6. 텔레그램 알림 시스템
7. Invalid Token 문제 해결
8. 사용성 개선과 프론트엔드 완성도 높이기 (현재 포스트)