Github Gist 로 효과적으로 코드 첨부하기
0. 글을 시작하며
아마 기술블로그를 관리하시는 분들이라면 많은 글에 "소스코드"를 포함하는 경우가 많을 것이라고 생각합니다. 물론 현재 제가 사용 중인 Tistory의 경우 "코드블럭"이라는 컴포넌트와 함께 여러가지 테마도 지원했지만, 이것에는 몇 가지 아쉬움이 있었습니다.
1. 화면크기나 비율에 따라서 코드가 읽기 좋게 보여지지 못하고 줄바꿈이 되어버리는 현상
2. 복사해서 사용할 때 가끔 엉뚱한 문자까지 함께 복사되어 사용이 불편한 현상
3. 코드가 눈에 확 들어오지 않는 아쉬움
4. 블로그에서 사용한 코드를 별도로 github과 직접 연동해서 관리하기 어려운 부분
정보를 공유하고 나누는 수단 중 하나인 기술 블로그에서 코드 가독성이 좋지 않은 코드 블럭을 사용한다는 것은 기술 블로그를 운영하고 관리하는 입장에서 결코 좋은 방법이 아니라는 생각이 들었습니다. 그리고 기술 블로그에서 사용하는 코드들을 효과적으로 연동하여 관리할 수 있도록 구성하는 것이 블로그를 관리하는 장기적인 측면에서도 더 유리하고 저 자신의 공부에도 더 좋다고 생각했습니다.
그래서 이번 글에서는 기술 블로그에서 소스코드를 첨부할 때 어떤 방법을 사용하는 것이 효과적인 방법인 지 알아보고자 합니다.
1. 시도해본 방법들
제목에 "효과적인" 이라는 표현을 사용했지만, 이 문제는 어느정도 개인의 취향에 영향을 받을 수 있는 문제이기 때문에 정답이 있는 것은 아니지만 저는 Tistory에서 제공하는 코드 블럭을 사용하지 않고 코드를 첨부하는 방법으로 다음 세 가지 방법을 고민했고, 활용했었습니다.
1. IDE나 에디터 상에서 코드를 작성하고 이를 부분 캡쳐해서 이미지로 첨부
2. Github에 해당 코드를 push 하고 해당 파일의 링크를 첨부
3. Notion의 코드블럭에 코드를 작성하고 해당 노트의 링크를 첨부
현재도 위의 세 가지 방법 중 한 가지 방법을 활용하는 분들이 있을 수도 있겠지만, 저는 각각에 대해서 다음과 같은 아쉬움이 남았습니다.
- IDE나 에디터 상에서 코드를 작성하고 이를 부분 캡쳐해서 이미지로 첨부
- 장점 : 자신이 보여주고자 하는 코드의 모습을 그대로 담아서 첨부할 수 있다. (테마, 줄바꿈 등)
- 단점 : 이미지기 때문에 페이지 로딩에 영향을 주고, 코드를 복사해서 사용할 수 없다.
- Github에 해당 코드를 push 하고 해당 파일의 링크를 첨부
- 장점 : 블로그에서 사용하는 코드를 1개의 repository에서 관리할 수 있어 좋다.
- 단점 : 사용자가 링크를 타고 들어가기 전까지는 코드의 내용을 볼 수 없다.
- Notion의 코드 블럭에 코드를 작성하고 해당 노트의 링크를 첨부
- 장점 : 많은 언어를 지원하고 사용이 편리한 Notion의 코드블럭을 활용할 수 있다.
- 단점 : 사용자가 링크를 타고 노트에 접근하기 전까지는 코드의 내용을 볼 수 없고, 관리가 어렵다 (이것도 결국은 노트...)
위에 간단히 정리해본 것처럼 각각의 방법들이 가지는 장단점이 있지만 꼭 하나씩 중요한 부분들을 놓치고 있었습니다. 그래서 제가 기술 블로그에서 코드를 첨부할 때 사용할 코드블럭이 가졌으면 하는 기능들을 다음과 같이 정리해보았습니다.
1. 다양한 언어를 지원하고, 작성된 코드에 대해서 가독성 좋게 보여줄 수 있는 깔끔한 UI를 제공할 수 있어야 함.
2. Github과 연동되어 기술 블로그에서 사용한 코드를 효율적으로 관리할 수 있어야 함.
이런 저런 방법들을 알아보고 시도해보다가 Tistory 상에서는 이러한 코드 블럭을 적용하는 것이 현실적으로 어려울 것 같아 포기하려던 중에 github gist를 활용한 소스코드 첨부 방법을 발견하게 되었습니다.
2. Github gist란?
아마 Github 프로필을 꾸미시면서 Github gist를 접해보신 분들이 있을 것 입니다 (제가 그랬습니다). Github Gist는 Github 내부에서 제공되는 서비스로서 우리가 Github의 사용을 통해 기대하는 코드 공유 기능을 동일하게 제공합니다. 하지만 소규모, 대형 프로젝트에 관계없이 효율적인 협업을 위한 UI를 제공하는 것이 Github이고, Gist는 이보다는 조금 더 작은 단위로서 프로젝트 중심이라기 보다는 짧은 code snippet을 공유하거나 간단한 메모를 기록하는 용도로서 더 사용하기 좋은 형태의 경량화된 느낌의 Github이라고 이해하시면 됩니다. (Stack Overflow에서도 이 주제에 대해서 많은 개발자들이 토론한 글이 있으니 궁금하신 분들은 참고하시기 바랍니다.)
https://stackoverflow.com/questions/6767518/what-is-the-difference-between-github-and-gist
What is the difference between GitHub and gist?
What is the purpose of gist and how is it different from regular code sharing/maintaining using GitHub?
stackoverflow.com
3. Github Gist를 활용해 소스코드를 첨부하는 방법
우선 자신의 Github 계정으로 접속한 뒤, 우측상단에 있는 '+' 버튼을 클릭한 뒤, "New Gist"를 클릭합니다.
그리고 위와 같이 Gist를 생성하는 데 필요한 정보들을 입력해주고, 첨부하고자 하는 코드를 작성합니다. 이때, 파일명에 자신이 사용하고자 하는 언어의 확장자명을 같이 적어줘야하는 부분을 주의해주세요. Gist가 확장자 명을 통해 작성 언어를 인식하게 되면 자동으로 Syntax Highlight가 되어 긴 코드가 아니라면 Gist에서 제공하는 에디터 상에서도 간편하게 코드를 작성하는 것이 가능합니다.
코드를 모두 작성했다면 오른쪽 아래에 있는 "Create secret gist"를 클릭합니다.
그러면 다음과 같이 Gist가 생성되고, 우측 상단에 "Embed"로 표시된 해당 코드를 임베드하기 위한 링크가 생성된 것을 볼 수 있습니다. 오른쪽에 있는 버튼을 클릭해서 해당 링크를 복사해줍니다.
그리고 이제 글을 작성하는 Tistory 에디터로 돌아옵니다. 오른쪽 상단을 보면 에디터 모드를 변경할 수 있는 버튼이 있는 데 이를 HTML 모드로 변경해줍니다.
그러면 위와 같이 자신이 작성하던 블로그 글이 HTML 문서로 변환되어 나타납니다. 여기서 아까 복사했던 Gist의 임베드 링크를 붙여넣기 하고 따로 저장할 필요없이 다시 에디터의 기본모드로 돌아옵니다.
이 과정을 모두 정상적으로 진행했다면 위와 같이 Gist를 통해 작성한 소스코드가 글에 잘 첨부된 것을 확인할 수 있습니다.
만약 동일하게 진행했음에도 첨부한 코드가 나타나지 않는다면?
Tistory에서 사용되는 특정 스킨들의 경우 페이지의 로딩 성능을 올리기 위한 지연로딩 기술이 적용된 경우, Github Gist로 첨부한 임베드 링크가 제대로 글에 나타나지 않는 현상이 있다고 합니다. 저도 최근 블로그 스킨을 변경하는 중에 이와 같은 현상이 있는 것을 확인하였습니다. 그래서 현재 자신의 블로그에서 사용하는 스킨이 지연로딩 기술을 사용하고 있지는 않은 지 확인 후 적용하여 사용할 필요가 있어 보입니다.
현재로서는 지연로딩이 적용된 상태에서 Gist 임베드로 첨부한 코드가 정상적으로 출력되도록 하는 방법은 찾지 못했습니다. 지연로딩 기술을 사용하는 스킨을 사용하시는 경우 우선 Tistory에서 제공하는 코드블럭을 사용하시거나 지연로딩 기술이 적용되지 않은 스킨 또는 스킨의 릴리즈 로그를 확인하셔서 지연로딩이 적용되지 않은 버전으로의 변경을 시도하시면 정상적으로 동작할 것 입니다.
4. 글을 마치면서
이렇게 Github Gist를 활용해서 블로그에 첨부한 코드를 첨부하면 사용자에게 보여지는 UI도 좋고, Gist에서 수정하면 해당 내용이 그대로 반영되기 때문에 관리하는 측면에서도 훨신 좋은 것 같습니다. 개인적으로는 Github repository에 있는 파일에 대해서 직접 임베드 링크를 생성해서 첨부할 수 있으면 Github 잔디심기도 함께 하면서 더 좋을 것 같지만 아쉽게도 Gist는 Github과는 분리되어 있어 작성한 내용이 contribution에 반영되지는 않습니다. (혹시 이와 관련된 다른 방법을 찾는 다면 수정하여 첨부하도록 하겠습니다.)
사실 블로그에 소스코드를 첨부하는 스타일은 개인의 취향이 반영되기 때문에 어떤 것이 옳고 틀리고는 없는 문제인 것 같습니다. 하지만 저의 경우 나름대로 기술 블로그에 코드를 첨부할 때 이를 좋은 가독성으로 제공함과 동시에 효율적 관리를 위한 방안을 여러 방법으로 고민하고 시도하면서 Gist를 활용하는 것도 하나의 좋은 방법이라는 결론을 얻었습니다.
혹시 저처럼 기술 블로그에 좋은 가독성으로 소스코드를 첨부하고 싶으신 분들이 계신다면 이 글이 도움이 되었길 바랍니다.
감사합니다.