개발자, 데이터 분석가, 혹은 IT 관련 지식을 공유하는 블로거라면 누구나 한 번쯤 겪는 고충이 있습니다. 바로 '코드'를 어떻게 블로그에 깔끔하고 보기 좋게 올릴 것인가 하는 문제입니다. 단순히 텍스트를 복사해서 붙여넣으면 가독성이 떨어지는 것은 물론, 들여쓰기가 망가지고 특수문자가 깨지는 등 온갖 문제가 발생합니다. 이런 문제를 해결하기 위해 등장한 것이 바로 '구문 강조(Syntax Highlighting)' 기술입니다.
많은 분들이 초기에 겪는 과정은 비슷합니다. 일단 글을 쓰고, 코드 부분을 HTML 편집 모드로 들어가 <pre>와 <code> 태그로 감싸는 수작업을 반복합니다. 하지만 이는 한두 번なら 몰라도, 포스팅이 늘어날수록 엄청난 비효율과 스트레스를 유발합니다. 저 또한 이 과정을 겪으며 더 나은 방법을 찾아 헤맸고, 그 과정에서 발견한 몇 가지 방법과 최종적으로 정착하게 된 가장 효율적인 솔루션을 공유하고자 합니다.
이 글에서는 단순히 코드를 예쁘게 만들어주는 온라인 도구를 소개하는 것을 넘어, 한 번의 설정으로 블로그 전체의 코드 블록 스타일을 관리하고, 가독성과 전문성을 극대화할 수 있는 자바스크립트 라이브러리(Prism.js, highlight.js) 적용법까지 상세하게 다룹니다. 이 글을 끝까지 읽으시면 더 이상 코드 블록 때문에 골머리를 앓는 일은 없으실 겁니다.
1. 가장 쉬운 첫걸음: 온라인 코드 하이라이터
가장 먼저 접하게 되는 방법은 웹사이트 형태의 온라인 코드 변환기입니다. 별도의 설치나 설정 없이, 웹사이트에 코드를 붙여넣기만 하면 바로 스타일이 적용된 HTML 코드를 생성해주는 방식입니다. 급하게 한두 개의 코드 조각을 포스팅해야 할 때 매우 유용합니다.
1-1. Hilite.me 와 ColorScripter
원문에서 소개된 hilite.me나 colorscripter.com과 같은 사이트들이 대표적입니다. 사용법은 매우 직관적입니다.
- 사이트에 접속하여 코드 입력창에 자신의 코드를 붙여넣습니다.
- 코드의 프로그래밍 언어를 선택합니다. (예: Java, Python, JavaScript)
- 원하는 디자인 테마(스타일)를 선택합니다.
- 'Highlight!' 또는 변환 버튼을 클릭합니다.
- 생성된 HTML 코드를 복사하여 블로그 글쓰기 에디터의 HTML 모드에 붙여넣습니다.
ColorScripter와 같은 온라인 도구는 직관적인 인터페이스를 제공합니다.
특히 ColorScripter는 생성된 코드를 복사해서 HTML 모드가 아닌, 일반 글쓰기 모드(Rich Text Editor)에 바로 붙여넣어도 스타일이 유지되는 편리함을 제공합니다. 하지만 이 편리함에는 몇 가지 명확한 한계가 존재합니다.
1-2. 온라인 도구의 한계점
- 유지보수의 어려움: 블로그의 디자인을 변경하거나 코드 테마를 통일하고 싶을 때, 이전에 작성했던 모든 게시물을 하나하나 찾아 들어가서 HTML 코드를 수정해야 합니다. 이는 사실상 불가능에 가까운 작업입니다.
- 과도한 인라인 스타일(Inline Styles): 생성된 HTML 코드는 <code><span style="color: #ff3399;"></code>과 같이 수많은 인라인 스타일 태그로 이루어져 있습니다. 이는 HTML 코드를 매우 지저분하고 길게 만들며, 웹 페이지 로딩 속도에 미미한 영향을 줄 수 있습니다.
- CSS 충돌 문제: 원문에서도 겪었던 문제입니다. 블로그 스킨(테마)에 이미 정의된 CSS 스타일과 온라인 도구가 생성한 CSS 스타일이 충돌하여 줄 번호가 틀어지거나 레이아웃이 깨지는 현상이 발생할 수 있습니다. 원문에서는 아래와 같은 코드로 임시방편의 해결을 보았습니다.
/* 원문 작성자가 시도했던 CSS 수정 코드 예시 */
.colorscripter-code-table td:first-child div div {
white-space: pre !important;
}
이처럼 특정 클래스를 찾아 강제로 스타일을 덮어쓰는 것은 좋은 해결책이 아닙니다. !important 속성은 다른 스타일과의 연쇄적인 충돌을 유발할 수 있기 때문입니다. 근본적인 문제는 이 방법이 '일회성'이며 '확장성'이 없다는 점입니다. 우리는 더 스마트하고 지속 가능한 방법이 필요합니다.
2. 전문가의 선택: 자바스크립트 구문 강조 라이브러리
온라인 도구의 단점을 완벽하게 보완하는 방법이 바로 자바스크립트 라이브러리를 활용하는 것입니다. 원리는 간단합니다. 블로그 스킨에 특정 자바스크립트 파일을 한 번만 추가해두면, 방문자가 페이지를 열 때마다 이 스크립트가 자동으로 페이지 내의 <pre><code>...</code></pre> 태그를 찾아 약속된 규칙에 따라 아름다운 스타일을 입혀줍니다.
장점은 명확합니다:
- ✍️ 깨끗한 원본 글: 포스팅 시에는 순수한 텍스트 코드만
<pre><code> 태그로 감싸주면 끝입니다. 지저분한 인라인 스타일이 전혀 없습니다.
- 🎨 일관성 및 유지보수: 블로그 스킨에 연결된 CSS 파일 하나만 수정하면 블로그 전체의 모든 코드 블록 디자인이 한 번에 변경됩니다.
- ⚙️ 풍부한 기능: 줄 번호 표시, 복사 버튼 추가, 특정 줄 하이라이트 등 다양한 부가 기능을 쉽게 추가할 수 있습니다.
- 🚀 성능: CDN을 활용하면 로딩 속도 저하도 거의 없습니다.
가장 대표적인 두 라이브러리는 Prism.js와 highlight.js입니다. 각각의 특징과 블로그 적용법을 자세히 알아보겠습니다.
2-1. Prism.js: 가볍고 강력하며 확장성 높은 라이브러리
Prism.js는 '가벼움'과 '모듈성'을 핵심 가치로 삼는 라이브러리입니다. 필요한 언어와 플러그인만 선택해서 나만의 맞춤형 스크립트 파일을 만들 수 있어 불필요한 코드 로딩을 최소화할 수 있습니다. 현대적이고 깔끔한 디자인 테마로 많은 사랑을 받고 있습니다.
Prism.js 적용 5단계 (티스토리/Blogger 기준)
단 한 번의 설정으로 모든 준비가 끝납니다. 차근차근 따라 해보세요.
1단계: 나만의 Prism.js 파일 빌드하기
먼저 Prism.js 공식 다운로드 페이지에 접속합니다. 여기서 필요한 구성요소를 직접 선택해야 합니다.
- Compression level: 'Minified version' (압축 버전)을 선택합니다.
- Themes: 원하는 디자인 테마를 하나 선택합니다. 처음이라면 'Default'나 어두운 테마인 'Okaidia', 'Tomorrow Night' 등이 무난합니다.
- Languages: 본인이 자주 사용하는 프로그래밍 언어를 모두 선택합니다. (예: Markup + HTML + XML, CSS, C-like, JavaScript, Java, Python, SQL, Bash...) 너무 많이 선택하면 파일 크기가 커지니, 꼭 필요한 것들 위주로 고릅니다.
- Plugins: 매우 중요한 부분입니다! 활용도를 극대화할 수 있는 필수 플러그인들을 선택하세요.
- Line Numbers: 코드 왼쪽에 줄 번호를 추가해줍니다. (필수)
- Toolbar: 코드 블록 오른쪽 상단에 여러 버튼을 추가할 수 있는 기반이 됩니다. (필수)
- Copy to Clipboard Button: Toolbar와 함께 사용되며, 코드를 쉽게 복사할 수 있는 버튼을 만들어줍니다. (강력 추천)
- Line Highlight: 특정 줄을 강조하고 싶을 때 사용합니다. (선택)
- Show Language: 코드 블록에 어떤 언어인지 표시해줍니다. (추천)
2단계: CSS 및 JS 코드 생성 및 복사
선택을 완료한 후, 페이지 하단으로 스크롤하면 'DOWNLOAD JS'와 'DOWNLOAD CSS' 버튼이 보입니다. 이 버튼을 클릭해서 파일을 다운로드할 필요는 없습니다. 우리는 CDN(Content Delivery Network)을 활용하여 더 빠르고 안정적으로 파일을 불러올 것입니다.
버튼 바로 아래에 생성된 코드가 있습니다. 이 코드를 복사해서 사용할 것입니다. 바로 이 코드가 여러분이 직접 선택한 기능들만 담고 있는 맞춤형 코드입니다.
<link href="생성된_CSS_링크.css" rel="stylesheet" />
<script src="생성된_JS_링크.js"></script>
만약 CDN 주소를 직접 얻고 싶다면, cdnjs 같은 CDN 사이트에서 직접 필요한 파일의 링크를 가져올 수도 있습니다.
3단계: 블로그 스킨 HTML에 코드 삽입하기
이제 복사한 코드를 블로그 스킨에 심어줄 차례입니다. 티스토리의 경우 [블로그 관리] → [스킨 편집] → [html 편집] 메뉴로 이동합니다.
- CSS 파일 링크: 복사한
<link ... > 태그는 HTML 문서의 <head> 와 </head> 사이 아무 곳에나 붙여넣습니다. 다른 CSS 링크들이 모여있는 곳에 넣으면 관리가 편합니다.
- JS 파일 링크: 복사한
<script ... > 태그는 페이지 로딩 속도를 위해 </body> 태그 바로 위에 붙여넣는 것이 가장 좋습니다.
4단계: 게시물에서 사용하기
모든 설정이 끝났습니다! 이제 글을 쓸 때 코드 블록을 삽입하는 방법은 매우 간단해집니다. 글쓰기 에디터를 HTML 모드로 변경하고, 아래 형식에 맞춰 코드를 작성하면 됩니다.
function sayHello(name) {
// 템플릿 리터럴을 사용한 문자열 조합
console.log(`Hello, ${name}!`);
}
sayHello('World');
<pre> 태그에 class="line-numbers" 를 추가하면 줄 번호 플러그인이 활성화됩니다.<code> 태그에 class="language-xxx" 형식으로 프로그래밍 언어를 명시해줘야 합니다. (예: language-javascript, language-python, language-css)- 중요!: 코드 내에
< 나 > 같은 HTML 특수 문자가 있다면, 반드시 < 와 > 로 변환(HTML Escaping)해야 합니다. 대부분의 최신 에디터는 이 과정을 자동으로 해주거나, 온라인 'HTML-encode' 도구를 사용하면 편리합니다.
5단계: 결과 확인
이제 글을 발행하고 확인해보세요. 여러분이 선택한 테마와 플러그인이 적용된 아름다운 코드 블록이 나타날 것입니다. 오른쪽 상단에는 복사 버튼도 달려있을 겁니다.
function createPerson(firstName, lastName) {
return {
firstName: firstName,
lastName: lastName,
fullName: function() {
return `${this.firstName} ${this.lastName}`;
}
};
}
const person = createPerson('John', 'Doe');
console.log(person.fullName()); // 결과: "John Doe"
Prism.js와 플러그인을 적용한 코드 블록의 최종 모습 예시
2-2. highlight.js: "그냥 작동하는" 쉬운 솔루션
highlight.js는 Prism.js와 쌍벽을 이루는 또 다른 인기 라이브러리입니다. 가장 큰 특징이자 장점은 '자동 언어 감지(Automatic language detection)' 기능입니다.
즉, Prism.js처럼 class="language-xxx"를 매번 지정해주지 않아도, highlight.js가 코드의 내용을 분석해서 "이건 파이썬 코드군!", "이건 자바스크립트야!" 하고 스스로 판단하여 알맞은 스타일을 적용해줍니다. 편의성 면에서는 최고라고 할 수 있습니다.
highlight.js 적용 4단계
적용 과정은 Prism.js보다 훨씬 간단합니다.
1단계: CDN 링크 가져오기
공식 사용법 페이지나 cdnjs와 같은 CDN 사이트로 갑니다. 두 개의 파일이 필요합니다.
- CSS 테마 파일: 원하는 테마를 고릅니다. 수많은 테마가 있으니 미리보기 사이트에서 확인해보세요. (예:
default.min.css, atom-one-dark.min.css)
- JS 코어 파일:
highlight.min.js 파일을 선택합니다. 이 파일 안에 수많은 언어 팩이 이미 포함되어 있습니다.
2단계: 블로그 스킨 HTML에 코드 삽입하기
Prism.js와 동일한 방법으로 스킨의 HTML을 편집합니다.
- CSS 링크는
<head> 안에, JS 링크는 </body> 태그 바로 위에 삽입합니다.
- 초기화 코드 추가: highlight.js는 라이브러리를 불러온 후, 이를 실행하라는 명령을 한 줄 추가해주어야 합니다.
3단계: 게시물에서 사용하기
이제 글을 쓸 때 HTML 모드에서 아래와 같이 아주 간단하게 작성하면 됩니다.
import pandas as pd
data = {'나라': ['한국', '미국', '일본'],
'수도': ['서울', '워싱턴 D.C.', '도쿄']}
df = pd.DataFrame(data)
print(df)
놀랍게도 class를 지정하지 않아도 자동으로 Python 코드로 인식하여 스타일을 적용해줍니다. 물론, 감지 정확도를 높이고 싶거나, 자동 감지가 잘 안되는 언어의 경우 Prism.js처럼 <code class="python"> 과 같이 명시해주는 것이 좋습니다. (highlight.js는 'language-xxx'가 아닌 'xxx' 형식의 클래스명을 사용합니다.)
4단계: 결과 확인
글을 발행하면 hljs.highlightAll(); 스크립트가 페이지의 모든 <pre><code> 블록을 찾아 자동으로 색을 입혀줍니다.
# highlight.js (atom-one-dark 테마) 적용 예시
import numpy as np
def create_random_matrix(rows, cols):
"""
지정된 크기의 랜덤 행렬을 생성합니다.
"""
matrix = np.random.rand(rows, cols)
return matrix
my_matrix = create_random_matrix(3, 4)
print(my_matrix)
3. Prism.js vs highlight.js: 무엇을 선택해야 할까?
두 라이브러리 모두 훌륭하지만, 약간의 지향점 차이가 있습니다. 선택에 도움이 되도록 표로 정리해 보았습니다.
| 특징 |
Prism.js |
highlight.js |
| 핵심 철학 |
경량성, 모듈성, 확장성 |
편의성, 범용성, 자동화 |
| 파일 크기 |
필요한 것만 선택하여 매우 가볍게 구성 가능 |
다양한 언어를 기본 포함하여 상대적으로 파일이 큼 |
| 언어 감지 |
수동 지정(class="language-xxx")이 원칙. (Autoloader 플러그인으로 가능) |
자동 언어 감지가 핵심 기능 |
| 부가 기능 |
플러그인 시스템이 매우 잘 되어 있음 (줄 번호, 복사 버튼 등) |
플러그인 생태계가 상대적으로 약함. (일부 기능은 직접 구현 필요) |
| 추천 대상 |
- 블로그 성능에 민감하고 최적화를 원하는 사용자
- 줄 번호, 복사 버튼 등 다양한 편의기능을 원하는 사용자 |
- 가장 쉽고 빠른 설정을 원하는 사용자
- 다양한 언어를 다루며 매번 클래스 지정이 귀찮은 사용자 |
개인적인 추천: 만약 당신이 "어떤 것을 써야 할지 정말 모르겠다"면, Prism.js에 필수 플러그인(Line Numbers, Toolbar, Copy to Clipboard Button)을 추가하여 사용하는 것을 권장합니다. 초기 설정이 5분 정도 더 걸릴 뿐이지만, 독자들에게 코드 줄 번호와 복사 버튼을 제공하는 것은 매우 큰 편의성을 주기 때문입니다.
결론: 스마트한 블로깅을 위한 최종 선택
개발 블로그에서 코드 블록의 가독성은 콘텐츠의 질을 결정하는 중요한 요소입니다. 더 이상 비효율적인 방식에 시간을 낭비하지 마세요.
온라인 코드 생성기는 급할 때 사용하는 비상약과 같습니다. 장기적이고 전문적인 블로그 운영을 위해서는 Prism.js나 highlight.js와 같은 자바스크립트 라이브러리를 도입하는 것이 현명한 투자입니다.
한 번의 설정으로 블로그 전체의 코드 품질을 높이고, 독자에게는 쾌적한 읽기 경험을, 스스로에게는 글쓰기의 효율성을 선물하세요. 이 가이드가 여러분의 기술 블로그를 한 단계 더 성장시키는 데 도움이 되기를 바랍니다.
