IT 기술

블로그 마크다운 코드블럭 색상 적용 문제 해결 방법 (Markdown Code Highlighting)

시남 2025. 3. 5. 15:57

마크다운(Markdown) 코드블럭에 색상이 적용되지 않는 경우가 있습니다. 주로 Markdown 렌더링 엔진 설정 문제 또는 코드 하이라이팅 플러그인 설정 오류 때문입니다. 이번 글에서는 코드블럭에 색상이 표시되지 않는 원인을 분석하고, Jekyll, Hexo, Hugo 등 블로그 플랫폼별 해결 방법을 자세히 정리해보겠습니다.

🎯 블로그 마크다운 코드블럭 색상 문제 해결 방법

1️⃣ 마크다운 코드블럭에 언어 지정하기 (Code Fencing)

마크다운에서 코드 하이라이팅이 적용되려면 코드블럭의 언어를 명확히 지정해야 합니다.

❌ 잘못된 예시 (색상 없음)

```
console.log("Hello, world!");
```

이렇게 작성하면 코드가 단순한 텍스트로 표시되며, 문법 하이라이팅이 적용되지 않습니다.

✅ 올바른 예시 (색상 적용)

```javascript
console.log("Hello, world!");
```

코드블럭의 첫 줄에 javascript, python 등의 언어를 명시하면, 코드 하이라이팅이 정상적으로 동작합니다.

2️⃣ Jekyll / Hexo / Hugo 블로그 코드 하이라이팅 설정하기

🔥 Jekyll (GitHub Pages 블로그)

GitHub Pages에서 Jekyll을 사용 중이라면 Rouge 또는 Pygments 하이라이터를 활성화해야 합니다.

📌 _config.yml 파일 수정

highlighter: rouge
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

🔥 Hexo 블로그 (Hexo 코드블럭 색상 적용)

Hexo에서는 highlight.js 또는 prism.js를 적용해야 합니다.

📌 _config.yml 설정 확인

highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace:

📌 Prism.js를 사용할 경우

prismjs:
  enable: true
  preprocess: true
  line_number: true
  tab_replace: ''

🔥 Hugo 블로그 (Hugo 마크다운 코드블럭 하이라이팅)

Hugo에서는 config.toml에서 syntax highlighting을 활성화해야 합니다.

📌 config.toml 설정 예시

pygmentsUseClasses = true
pygmentsCodeFences = true

이 설정을 추가하면 Hugo에서도 코드 하이라이팅이 정상적으로 적용됩니다.

3️⃣ CSS 및 JavaScript 문제 해결하기

코드블럭이 HTML로 변환될 때, 스타일이 적용되지 않는 경우도 있습니다.

✅ highlight.js 적용하기

1️⃣ highlight.js CDN 추가 (HTML <head> 태그에 삽입)

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

2️⃣ 코드 블럭 스타일이 pre code 태그에 적용되는지 확인

pre code {
  background: #282c34;
  color: #abb2bf;
  padding: 1rem;
  border-radius: 5px;
  font-size: 14px;
  overflow-x: auto;
}

이렇게 설정하면 코드블럭이 깔끔하게 표시됩니다.

4️⃣ Markdown 렌더링 엔진 확인하기

일부 블로그 플랫폼에서는 기본적으로 코드 하이라이팅이 비활성화될 수 있습니다. 아래 내용을 참고하여 Markdown 엔진을 확인하세요.

📌 GitHub Pages (Jekyll 블로그): _config.yml에서 kramdown 사용 여부 확인
📌 Hexo 블로그: hexo-renderer-marked 대신 hexo-renderer-pandoc 사용 가능
📌 Hugo 블로그: pygmentsUseClasses = true 설정

🚀 마무리: 블로그 코드 하이라이팅 문제 해결 정리

1️⃣ 코드블럭에 언어를 지정한다. (```javascript 등)
2️⃣ Jekyll, Hexo, Hugo 블로그별 코드 하이라이팅 설정을 확인한다.
3️⃣ highlight.js 또는 prism.js를 적용해본다.
4️⃣ CSS 및 JavaScript 충돌이 있는지 점검한다.