기술 블로그를 쓰면서 코드를 그냥 텍스트로 붙여넣은 적이 있다. 코드인지 본문인지 구분도 안 되고, 들여쓰기도 다 무너지고, 색상도 없이 그냥 흑백 텍스트. 그 글을 나중에 다시 봤을 때 읽고 싶지가 않았다. 내가 쓴 글인데도 눈이 안 가더라. 처음엔 그게 당연한 건 줄 알았다. 기술 블로그니까 내용이 중요하지 꾸밈이 뭐가 중요하냐고. 그 생각이 얼마나 틀렸는지는 나중에야 알았다.
반대로 코드 블록이 잘 정돈된 기술 글은 읽기 전부터 신뢰가 간다. 요리 레시피책에서 재료와 조리법이 명확하게 정리된 것과 그냥 글로 쭉 써놓은 것의 차이라고 할까. 같은 레시피인데 보기 좋게 정리된 쪽이 훨씬 따라 하고 싶어진다. 코드 블록도 마찬가지다. 구문 강조가 있으면 어디가 키워드고 어디가 값인지 한눈에 들어온다. 이건 미적인 취향의 문제가 아니라 정보 전달의 문제다.
Highlight.js는 코드 블록에 자동으로 구문 강조를 입혀주는 라이브러리다. CSS 몇 줄, JavaScript 몇 줄이면 평범한 코드 블록이 에디터 수준으로 보이기 시작한다. 글의 전문성을 높이는 데 이것만큼 효과적인 게 없다고 생각한다. 그리고 이걸 진작 알았더라면 훨씬 일찍 시작했을 텐데, 라는 아쉬움도 있다.
처음엔 꾸밀 필요가 있나 싶었다
솔직히 기술 블로그를 처음 시작했을 때 코드를 그냥 일반 텍스트로 붙여넣어도 된다고 생각했다. 코드면 코드지, 꾸밀 필요가 있나 싶었던 거다. 내용이 좋으면 독자가 알아서 읽겠지 하는 막연한 믿음이 있었다. 그런데 몇 달 뒤 그 글을 다시 열었을 때, 내가 쓴 글인데도 읽고 싶지가 않았다. 들여쓰기는 다 무너져 있고, 어디까지가 코드고 어디서부터 설명인지도 구분이 안 됐으니까. 그때부터 코드 블록 스타일링을 진지하게 들여다보기 시작했다.
처음에는 다른 기술 블로그를 보다가 코드가 에디터처럼 색상별로 구분돼 있는 걸 봤다. 키워드는 파란색, 문자열은 초록색, 주석은 회색으로 딱딱 나뉘어 있는 그 모습이 인상적이었다. 저게 뭔가 싶어서 개발자 도구로 소스를 열어봤더니 highlight.js라는 이름이 보였다. 그 이름을 처음 봤을 때는 "이런 게 있었구나" 하는 단순한 감탄이었는데, 실제로 써보고 나서는 "왜 진작 몰랐지"로 바뀌었다.
Highlight.js는 JavaScript 기반의 구문 강조(Syntax Highlighting) 라이브러리다. 여기서 구문 강조란 코드의 문법 요소를 색상으로 구분해서 가독성을 높여주는 기능을 말한다. 프로그래머들이 IDE나 코드 에디터에서 당연하게 보던 그 색상 구분을 웹 페이지에서도 구현해주는 도구다. 당연히 있어야 할 기능을 당연하게 쓸 수 있게 해준다는 점에서, 이 라이브러리의 존재 이유는 명확하다.
적용 방법이 이렇게 단순할 줄은 몰랐다
직접 써봤는데, 적용 방법이 정말 단순했다. CDN(콘텐츠 전송 네트워크, 전 세계에 분산된 서버를 통해 파일을 빠르게 불러오는 방식)을 활용해 head 태그 안에 CSS 1줄, JS 2줄을 추가하고, 스크립트 하단에 hljs.highlightAll()을 한 번 호출하면 끝이다. "설마 이게 다야?" 싶었는데 진짜로 이게 전부였다. 복잡한 설정이 필요할 거라고 예상했던 내 편견이 완전히 깨진 순간이었다. 몇 주를 미룬 게 허탈할 정도였다.
한 가지 반드시 짚고 넘어갈 부분이 있다. HTML에서 코드를 표시할 때 pre와 code 태그 조합을 써야 한다는 점이다. pre 태그는 Preformatted Text의 약자로, 줄바꿈과 공백, 들여쓰기를 있는 그대로 유지해주는 태그다. code 태그만 단독으로 쓰면 줄바꿈이 무시되고 코드가 한 줄로 뭉개져서 나온다. 내 초창기 블로그가 딱 이 상태였다. 당시에는 왜 코드가 이상하게 보이는지 이유조차 몰랐다. MDN Web Docs를 보고 나서야 이해했는데, 이걸 알고 나면 "당연히 이래야 하는 거잖아" 싶을 정도로 기본적인 내용이다. 기본을 모른 채 결과만 보고 있었던 거다.
특정 언어를 명시하려면 code 태그에 language-javascript 형식으로 클래스를 지정하면 된다. 자동 언어 감지 기능도 있긴 한데, 이건 좀 다르다. 짧은 코드 스니펫이나 덜 알려진 언어에서 엉뚱한 색상이 입혀지는 경우를 몇 번 겪었다. 특히 SQL이나 셸 스크립트를 자동 감지에 맡겼다가 완전히 다른 언어로 인식된 적이 있었다. 독자가 코드를 잘못 이해할 수도 있는 상황이었다. 그 이후로는 언어 클래스를 항상 직접 명시하는 습관을 들였다. 자동 감지는 편하지만, 편함 뒤에 숨겨진 오류 가능성은 감수하기 어렵다.
체감한 변화는 예상보다 빨리 왔다
Highlight.js를 달고 나서 변화는 생각보다 명확했다. 코드가 색상으로 구분되니 키워드, 문자열, 주석이 한눈에 들어왔다. 더 놀라운 건 독자 반응이었다. "코드 그대로 써봤는데 됐어요" 같은 댓글이 처음으로 달리기 시작했다. 이 댓글 하나가 나에게는 굉장히 의미 있었다. 누군가가 내 글을 보고 실제로 따라 해봤다는 뜻이니까. 코드가 깔끔하게 보이니까 따라 해보는 독자가 생긴 것이다.
글을 쓰는 나도 달라졌다. 코드 가독성이 높아지니 오탈자를 더 쉽게 발견하게 됐다. 예전에는 흑백으로 이어진 코드를 눈으로 훑는 게 힘들었는데, 색상이 생기니까 이상한 부분이 눈에 훨씬 잘 띄었다. 변수명을 잘못 쓴 것도, 괄호가 빠진 것도 구문 강조 덕분에 먼저 보이기 시작했다. 스타일링이 단순히 보기 좋음의 문제가 아니라 품질 관리와도 연결된다는 걸 그때 깨달았다.
테마 변경과 복사 버튼, 그리고 줄 번호의 함정
Highlight.js의 또 다른 장점은 테마 전환이 쉽다는 점이다. github-dark, github, vs2015, atom-one-dark 등 수십 가지 테마를 제공하는데, CDN URL에서 스타일 이름 부분만 바꾸면 즉시 적용된다. 처음엔 github-dark 테마를 썼다가 블로그 배경색과 안 맞는다 싶어서 github 테마로 바꿨다. 코드 한 줄 수정 없이 CSS 링크 하나만 교체했고, 30초도 안 걸렸다. 이 정도의 유연함은 처음 사용할 때 기대하지 못했던 부분이었다.
복사 버튼도 직접 구현해봤는데, Clipboard API를 활용하면 된다. Clipboard API란 브라우저에서 클립보드 읽기와 쓰기를 지원하는 웹 표준 인터페이스다. navigator.clipboard.writeText() 메서드로 코드 블록의 텍스트를 클립보드에 복사하는 기능을 구현할 수 있다. 버튼을 코드 블록 우측 상단에 띄워두고, 클릭 시 해당 pre 안의 텍스트를 가져와 복사하는 방식이다. JavaScript 10줄 남짓이면 된다. 복사 버튼 하나가 독자 경험을 얼마나 바꾸는지는, 달고 나서 피드백을 받아보면 바로 체감이 된다.
줄 번호 기능은 얘기가 좀 다르다. highlightjs-line-numbers라는 별도 플러그인을 추가해야 하는데, 데스크톱에서는 줄 번호가 깔끔하게 보이지만 모바일에서 화면이 좁아지면 줄 번호 열과 코드 영역이 어긋나는 레이아웃 문제가 발생했다. 처음엔 이게 내 CSS 실수인 줄 알고 한참 들여다봤는데, 플러그인 자체의 모바일 대응이 불완전한 문제였다. 기술 블로그 독자 중 모바일 비율이 적지 않다는 걸 감안하면 이 플러그인은 신중하게 써야 한다. 도입 전에 반드시 실제 기기에서 테스트해보길 권한다.
Prism.js와 비교하면서 든 생각
Prism.js와 비교하는 시각도 있다. Prism.js는 플러그인 시스템이 더 유연하고 확장성이 높다. 줄 번호, 라인 하이라이트, 코드 복사까지 공식 플러그인으로 깔끔하게 지원한다. 기능 면에서는 분명히 Prism.js가 앞선다고 생각한다. 이건 솔직히 인정해야 하는 부분이다.
그런데 개인적으로는 Highlight.js를 먼저 배운 게 시작 단계에서는 옳은 선택이었다고 본다. Prism.js는 초기 세팅 과정이 상대적으로 복잡하다. 처음부터 Prism.js를 붙잡고 씨름했다면 코드 블록 하나 예쁘게 만들겠다고 포기했을 가능성이 충분히 있다. 블로그 운영에서 중요한 건 완벽한 도구를 고르는 것보다 일단 시작하는 것이다. Highlight.js는 CDN 3줄이라는 단순함이 그 진입 장벽을 확실히 낮춰준다. 블로그 규모가 커지면 Prism.js로 전환하는 것도 고려해볼 만하지만, 처음에 쉬운 도구로 시작한 덕분에 포기하지 않고 계속 쓸 수 있었다는 게 더 중요하다.
기술 블로그에서 코드 블록은 단순한 꾸미기가 아니다. 독자가 코드를 읽고 실제로 따라 해볼 수 있느냐 없느냐를 가르는 기준선이다. Highlight.js 하나로 그 기준을 넘기는 데 5분이면 충분하다. 아직 코드를 텍스트로만 붙여넣고 있다면, CDN 3줄부터 추가해보길 권한다. 적용하고 나서 블로그를 다시 열었을 때, 왜 진작 안 했지 싶은 기분이 들 거다.
참고
https://highlightjs.org
https://cdnjs.cloudflare.com
https://developer.mozilla.org/ko/docs/Web/HTML/Element/pre