블로그스팟 글에 코드 블록 삽입하는 법

 

블로그스팟에서 개발 관련 글을 쓰려는데 코드 블록 기능이 없어서 당황했다면, highlight.js 라이브러리 하나면 깔끔한 신택스 하이라이팅까지 해결된다.

블로그스팟으로 기술 블로그를 운영하겠다고 마음먹고 첫 글을 쓰는데, 코드를 넣을 방법이 없어서 멘붕이 왔다. 티스토리는 버튼 하나로 코드 블록이 들어가잖아요. 근데 블로그스팟 에디터에는 그런 게 없더라고요. 코드를 그냥 텍스트로 붙여넣으면 들여쓰기가 다 깨지고, 줄바꿈도 엉망이 되고. 처음에는 스크린샷을 찍어서 이미지로 넣을까도 생각했는데, 그러면 복사도 안 되고 SEO에도 최악이라 포기했다.

이리저리 검색하면서 highlight.js라는 라이브러리를 발견했고, GitHub Gist를 활용하는 방법도 알게 됐다. 둘 다 써보니 상황에 따라 쓰임이 다르더라고요. 이 글에서 두 가지 방법 다 정리해놓을 테니까 본인 상황에 맞는 걸 골라 쓰면 된다.

블로그스팟에 코드 블록이 없다고?

블로그스팟(Blogger)은 구글에서 제공하는 무료 블로그 플랫폼인데, 글꼴 변경이나 자동 임시저장 같은 기능은 괜찮다. 문제는 개발자에게 필수인 코드 블록 삽입 기능을 기본으로 제공하지 않는다는 거다.

에디터에서 Courier 폰트를 적용할 수는 있거든요. 근데 이걸 코드 블록처럼 쓰면 각 줄이 별도 문단으로 처리되면서 줄 간격이 벌어진다. 보기 흉하다. HTML 보기로 전환해서 <pre> 태그로 감싸면 줄 간격은 해결되지만, 구문 강조(syntax highlighting)가 안 되니까 코드가 시각적으로 묻혀버린다.

그래서 필요한 게 외부 라이브러리다. 블로그스팟은 테마 HTML을 직접 편집할 수 있어서, 여기에 자바스크립트 라이브러리를 로드하는 코드를 넣으면 된다. 대표적인 게 highlight.js인데, 192개 이상의 프로그래밍 언어를 지원하고 498개 넘는 테마까지 제공한다.

아니면 아예 외부 서비스를 임베드하는 방법도 있다. GitHub Gist가 대표적이고, Carbon처럼 코드를 이미지로 변환하는 도구도 있다. 근데 Carbon은 이미지라서 검색엔진이 코드 내용을 읽을 수 없고, 방문자가 복사도 못 하니까 실용적이지 않다고 느꼈다.

📊 실제 데이터

highlight.js 공식 사이트(highlightjs.org) 기준 최신 버전은 11.11.1이고, CDN으로 바로 가져다 쓸 수 있다. 오픈소스(BSD-3-Clause 라이센스)라 개인 블로그든 상업용이든 제한 없이 사용 가능하다.

highlight.js 테마에 설치하기

한 번만 설정해두면 이후에는 글 쓸 때마다 자동으로 적용되니까, 이 과정이 좀 귀찮더라도 참고 따라 하면 된다. 처음에 테마 HTML 여는 게 좀 무섭긴 한데, 딱 3줄만 넣으면 끝이다.

블로거 대시보드 왼쪽 메뉴에서 테마(Theme)를 선택한다. 테마 화면이 뜨면 "맞춤설정(Customize)" 버튼 옆에 드롭다운 화살표가 있는데, 그걸 눌러서 "HTML 편집(Edit HTML)"으로 들어간다. 코드가 잔뜩 나오는데 겁먹지 마시고, <head> 태그를 찾아서 바로 아래에 다음 코드를 붙여넣으면 된다.

넣어야 할 코드는 이거다:

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

첫 번째 줄은 코드 블록의 CSS 스타일시트를 불러오는 거고, 두 번째 줄이 highlight.js 라이브러리 본체, 세 번째 줄이 페이지 로딩 시 자동으로 코드 블록을 찾아 하이라이팅을 적용하라는 명령이다. 붙여넣었으면 우측 상단의 저장 아이콘을 누른다.

여기서 주의할 게 있다. 특정 언어만 따로 추가하고 싶으면 두 번째 줄과 세 번째 줄 사이에 언어 파일을 하나 더 불러올 수 있다. 예를 들어 Go 언어를 추가하려면:

<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/languages/go.min.js"></script>

기본 번들에 이미 Python, JavaScript, HTML, CSS, Java, C++ 같은 주요 언어가 포함되어 있으니까 웬만하면 추가 안 해도 된다. Dart나 Kotlin 같은 언어를 쓸 때만 별도로 로드해주면 되더라고요.

글 작성할 때 코드 넣는 실전 방법

테마 설정이 끝났으면 이제 실제로 글에 코드를 넣어보자. 에디터 좌측 상단에 연필 아이콘(✐)이 있는데, 그걸 눌러서 HTML 보기로 전환한다. "작성" 모드와 "HTML" 모드가 토글되는 구조거든요.

코드를 넣고 싶은 위치에 이런 형태로 작성하면 된다:

<pre><code> 여기에 코드를 붙여넣는다 </code></pre>

이렇게만 하면 highlight.js가 자동으로 언어를 감지해서 구문 강조를 적용해준다. 파이썬이든 자바스크립트든 알아서 잡아낸다. 근데 가끔 자동 감지가 틀릴 때가 있거든요. 그럴 땐 language 클래스를 직접 지정해주면 확실하다:

<pre><code class="language-python"> def hello(): print("Hello, Blogspot!") </code></pre>

language- 뒤에 python, javascript, html, css, java, cpp 같은 식으로 넣으면 된다. 처음에 이걸 몰라서 자동 감지에만 의존했다가, 짧은 코드 조각이 엉뚱한 언어로 하이라이팅되는 걸 보고 당황한 적이 있다.

💡 꿀팁

코드 안에 HTML 태그가 들어있다면 <, >, & 같은 특수문자를 HTML 엔티티(&lt; &gt; &amp;)로 변환해야 한다. 안 그러면 브라우저가 그걸 실제 태그로 해석해버려서 코드가 깨진다. "HTML 엔티티 변환기"를 검색하면 온라인 도구가 많으니까 복사해서 변환 후 붙여넣으면 편하다.

한 가지 더. "작성" 모드에서 코드를 먼저 붙여넣고 나중에 HTML 모드로 가면 블로거가 자동으로 <p> 태그를 삽입해놓는다. 그래서 코드 사이사이에 불필요한 문단 태그가 끼어서 레이아웃이 망가진다. 코드는 처음부터 HTML 모드에서 직접 넣는 게 깔끔하다. 아니면 작성 모드에서 "여기에코드" 같은 플레이스홀더를 적어두고, HTML 모드에서 그 부분을 찾아 <pre><code>로 교체하는 방법도 괜찮더라고요.

GitHub Gist로 더 간단하게 삽입하기

테마 HTML 건드리는 게 부담되거나, 코드를 자주 수정해야 하는 상황이면 GitHub Gist가 오히려 낫다. Gist에 코드를 올려놓고 임베드 코드를 복사해서 블로그에 붙여넣는 방식이거든요.

방법은 간단하다. gist.github.com에 접속해서 GitHub 계정으로 로그인한다. 코드를 입력하고 파일 이름에 확장자까지 넣어준다(예: main.py, index.html). 확장자를 넣어야 언어를 인식해서 구문 강조가 제대로 된다. "Create secret gist" 또는 "Create public gist"를 누르면 Gist가 생성된다.

생성된 Gist 페이지 우측 상단에 Embed 드롭다운이 있다. 거기서 나오는 <script src="..."> 형태의 코드를 복사한다. 블로그스팟 글쓰기에서 HTML 모드로 전환한 뒤 원하는 위치에 붙여넣으면 끝이다.

항목 highlight.js GitHub Gist
초기 설정 테마 HTML 편집 필요 설정 없음
코드 수정 글 편집에서 직접 수정 Gist에서 수정하면 블로그 자동 반영
디자인 커스텀 498개 테마 선택 가능 GitHub 기본 디자인 고정
페이지 속도 CDN 로드 (가벼움) 외부 스크립트 호출 (약간 느림)
SEO 코드가 HTML 본문에 포함됨 iframe으로 로드되어 검색엔진 인식 약함

Gist의 가장 큰 장점은 코드 수정이 편하다는 건데, SEO 측면에서는 highlight.js가 낫다. 검색엔진이 코드 내용을 직접 크롤링할 수 있으니까. 개발 튜토리얼 블로그를 운영한다면 highlight.js 쪽이 유리하고, 단순히 코드 공유용이면 Gist가 편하다.

코드 블록 디자인 입맛대로 바꾸기

highlight.js의 기본 테마(default)가 밝은 배경이라 대부분의 블로그 디자인과 잘 어울리긴 한다. 근데 어두운 테마를 원하거나, 내 블로그 색상과 맞추고 싶을 때가 있잖아요. 테마 변경은 CDN 링크의 CSS 파일명만 바꾸면 된다.

예를 들어 VS Code의 어두운 테마와 비슷한 느낌을 원하면:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/atom-one-dark.min.css">

default.min.css 부분을 원하는 테마 파일명으로 교체하면 끝이다. 인기 있는 테마 몇 가지를 꼽자면 github(GitHub 스타일 밝은 테마), atom-one-dark(VS Code 느낌 어두운 테마), monokai(Sublime Text 감성), nord(차분한 파스텔 톤)가 있다. highlight.js 공식 사이트 데모 페이지(highlightjs.org/demo)에서 미리보기가 가능하니까 직접 눈으로 비교해보는 게 좋다.

코드 블록 자체의 모양(둥근 모서리, 패딩, 배경색 등)을 더 세밀하게 조정하고 싶으면 블로거 테마의 CSS에 추가 스타일을 넣을 수 있다. 블로거 대시보드에서 테마 → 맞춤설정 → 고급 → CSS 추가(Add CSS)로 가면 커스텀 CSS를 넣는 칸이 있다. 거기에 이런 식으로 작성한다:

pre code { border-radius: 8px; padding: 20px; font-size: 14px; line-height: 1.6; }

처음에 border-radius를 너무 크게 줬다가 코드가 안쪽으로 너무 밀려 들어가서, 8px 정도가 적당하더라고요. font-size도 14~15px이 모바일에서 읽기 편한 크기였다. 16px 이상으로 가면 긴 코드 줄이 가로 스크롤 없이 안 들어간다.

처음에 다 겪는 실수 모음

블로그스팟에 코드 블록을 넣으면서 겪은 삽질을 공유하려고 한다. 검색해보면 나만 그런 게 아니었다.

<pre><code> 안에 코드를 넣었는데 하이라이팅이 안 되는 경우가 있다. 이건 높은 확률로 <script>hljs.highlightAll();</script> 줄을 빠뜨렸거나, CDN 링크가 잘못된 거다. 브라우저 개발자 도구(F12)에서 콘솔을 열어보면 404 에러가 뜨는 걸 확인할 수 있다.

또 하나. 작성 모드에서 코드를 편집하면 블로거가 멋대로 <br> 태그나 <div>를 삽입한다. 이러면 코드 포맷이 완전히 망가진다. 코드 블록 관련 편집은 무조건 HTML 모드에서만 해야 한다. 작성 모드로 잠깐 전환했다가 다시 돌아와도 이미 태그가 섞여있을 수 있어서 주의가 필요하다.

⚠️ 주의

블로거의 "작성" 모드와 "HTML" 모드를 왔다 갔다 하면 에디터가 HTML 구조를 임의로 변경하는 경우가 있다. 코드 블록을 넣은 뒤에는 되도록 HTML 모드에서만 편집하고, 미리보기로 확인하는 습관을 들이는 게 안전하다.

코드 안에 <script>나 <div> 같은 HTML 태그가 포함되어 있을 때 엔티티 변환을 안 하면, 브라우저가 그걸 코드가 아니라 실제 HTML로 해석한다. 코드 블록 안에서 태그가 사라지거나, 페이지 레이아웃이 깨지거나, 심하면 자바스크립트가 실행돼버리기도 한다. 특히 블로그에 HTML/CSS 튜토리얼을 쓰는 사람이라면 이 부분을 항상 신경 써야 한다.

인라인 코드(문장 중간에 짧게 들어가는 코드)는 highlight.js가 처리를 못 한다. highlight.js는 <pre><code> 블록 단위로만 작동하거든요. 인라인 코드는 Courier 폰트를 적용하거나, 배경색을 살짝 넣어서 구분하는 방식으로 처리해야 한다.

자주 묻는 질문

Q. highlight.js를 넣으면 블로그 로딩 속도가 느려지나요?

CDN에서 가져오는 파일 크기가 약 40KB 정도라 체감할 수준은 아니다. 구글 PageSpeed에서 측정해봐도 점수 차이가 거의 없었다. 다만 추가 언어 파일을 10개씩 로드하면 그만큼 늘어나니까 필요한 것만 추가하는 게 좋다.

Q. 블로그스팟 모바일 앱에서도 코드 블록이 보이나요?

모바일 브라우저에서 블로그를 열면 정상적으로 보인다. 다만 블로거 관리용 모바일 앱의 에디터에서는 HTML 편집이 제한적이라, 코드 블록 작성은 PC 브라우저에서 하는 걸 권장한다.

Q. highlight.js 버전이 업데이트되면 CDN 링크를 바꿔야 하나요?

기존 버전도 CDN에 계속 남아있어서 당장 문제는 없다. 다만 새 버전에서 언어 지원이 추가되거나 버그가 수정될 수 있으니까, 반년에 한 번 정도는 공식 사이트에서 최신 버전을 확인하고 업데이트하는 게 좋다.

Q. highlight.js와 GitHub Gist를 한 블로그에서 동시에 쓸 수 있나요?

충돌 없이 동시 사용이 가능하다. Gist는 iframe으로 별도 로드되고 highlight.js는 본문의 pre code 태그만 처리하기 때문에 서로 간섭하지 않는다.

Q. 코드에 줄번호를 넣고 싶은데 어떻게 하나요?

highlight.js 자체에는 줄번호 기능이 없다. highlightjs-line-numbers.js라는 별도 플러그인을 추가로 설치하면 된다. CDN에서 제공하니까 테마 HTML에 스크립트 한 줄만 더 추가하면 적용 가능하다.

본 포스팅은 개인 경험과 공개 자료를 바탕으로 작성되었으며, 전문적인 의료·법률·재무 조언을 대체하지 않습니다. 정확한 정보는 해당 분야 전문가 또는 공식 기관에 확인하시기 바랍니다.

👉 함께 읽으면 좋은 글: 블로그스팟 HTML 편집 기초, 모르면 손해보는 태그 5개

👉 함께 읽으면 좋은 글: 애드센스 승인 대행 업체에 돈 쓰고 후회한 이유

👉 함께 읽으면 좋은 글: 블로그스팟 사이드바 위젯 직접 정리해봤더니 체류시간이 달라졌다

블로그스팟에 코드 블록을 넣는 건 highlight.js 설치(테마에 3줄 추가) 후 글 작성 시 <pre><code> 태그로 감싸는 게 핵심이다. 테마 수정이 부담되면 GitHub Gist 임베드도 좋은 대안이고, 두 가지를 상황에 맞게 섞어 쓰면 된다.

개발 튜토리얼을 주력으로 쓰는 블로그라면 highlight.js로 통일하는 게 SEO에도, 디자인 일관성에도 유리하다. 코드를 간간이 공유하는 정도면 Gist가 관리 부담이 덜하다.

도움이 됐다면 댓글로 어떤 방법을 선택했는지 알려주세요. 블로그스팟 운영 관련 질문도 편하게 남겨주시면 같이 고민해볼게요.

댓글

댓글 쓰기