블로그 마이그레이션 (feat. docusaurus)

기존에 사용하던 SSG(Static Site Generator)를 hexo에서 docusaurus으로 변경한 작업을 공유해봅니다.

왜 변경했는가?

사실 큰 이유는 없습니다. (잉...?😓) 단지, 테마를 변경하고 싶었으나, 사용하던 기존 테마에 의존성이 강하다 보니 이를 다른 테마로 변경하는 비용과 다른 SSG로 변경하는 비용이 비슷하다고 생각했고 그렇게 다른 SSG 도구(?)들을 찾아보게 되었습니다.

다른 SSG 도구들

대표적으로 https://jamstack.org/generators/ 를 참고하시면 여러 도구들을 찾아볼 수 있는데요. 이왕, 바꾸는김에 jvm 계열 언어로 변경해볼까도 생각했지만 관련 플러그인이나 테마가 너무 적었기에 결국에는 javascript 쪽으로 다시 찾아보게 되었습니다.

Gatsby

https://www.gatsbyjs.com/

요즘 이 도구가 가장 많이 보여 한번 시도를 해봤습니다. 결과적으로 사용하지 않았지만, 다음과 같은 이유로 Gatsby를 사용하지 않았습니다.

1. React를 깊게 알지 못하기 때문에 오히려 불편함
2. 단순히 블로그만 원했던 나에겐 커스텀 요소가 많았음
3. 결국 커스텀을 하기 되면 Gatsby 의존성이 강해질 것이라고 판단

Docusaurus

https://docusaurus.io/

facebook에서 만든 SSG 도구로 개인적으로는 커스텀이 그나마 적었고 쉬웠습니다. 그리고 또 다른 개인적인 이유로는 초록색을 좋아하기 때문에 vue 공식 홈페이지를 모방한(?) hexo-theme-vexo를 사용했었는데요. docusaurus는 기본적으로 초록색이기 때문에(?) 별다른 테마를 적용하지 않아도 될 만큼 만족스러운 테마였습니다.

만들어보기

https://docusaurus.io/docs/installation 를 참고하시면 명령어 한줄로 손쉽게 만들 수 있는데요. 만들어진 기본구조는 공식 홈페이지를 참고하시면 자세히 설명되어 있습니다.

npx create-docusaurus@latest [name] [template]

npx create-docusaurus@latest website classic

변경한 부분

hexo로 사용하던 기능은 그대로 옮겨가는게 최종 목표였는데요.

SEO

대부분의 SSG도구들과 마찬가지로 기본적으로 해주기 때문에 따로 설정하지 않았습니다.

Google Adsense

플러그인이 존재하긴 했지만, 간단한 기능이였기 때문에 local plugin을 만들었습니다.

참고) https://docusaurus.io/docs/api/plugin-methods / injectHtmlTags

Google Analytics

Google Analytics 4 경우에는 gtag를 사용한다고 하여, gtag로 변경했습니다.

참고) 보다 많은 기능을 제공하며, 기존에 UA-로 시작하는 ID로도 매핑되니 문제없이 적용할 수 있습니다.

검색 노출

Google, Naver 같은 검색 서비스에 잘 노출이 되도록 meta tag를 추가해야하는데요. themeConfig#metadata를 활용하면 손쉽게 추가할 수 있습니다.

// ...
metadata: [
    {name: 'google-site-verification', content: 'XXXXXXX'},
    {name: 'naver-site-verification', content: 'XXXXXXX'}
],
// ...

GitHub Action

공식 홈페이지를 참고하시면 손쉽게 해결할 수 있습니다. (deployment)

Algolia 검색창

Docusaurus 문서를 보면서 알게된 사실은 DocSearch라는게 존재하는데 이게 sitemap을 크롤링해서 인덱싱을 해주고 UI까지 만들어줍니다. hexo를 사용할 땐 html, css, script를 전부 직접 만들었었는데... 그럴 필요가 없어졌습니다. 👍

hexo-tag-gdemo

제일 난감했던 부분인데요. hexo에서는 tag라는 기능이 있어 별도의 문법을 통해 커스텀 기능을 추가할 수 있었습니다. 그래서 이를 활용해서 hexo-tag-gdemo라는걸 만들었는데... 이를 다른 방법으로 해결해야했습니다. (군데군데 사용하고 있었습니다. 🥲)

처음에는 plugable하게 remark, reshape 개념을 좀 더 공부해보고 적용해볼까 했지만, 아직은 너무 과하단 생각이들어서 React로 간단하게 컴포넌트를 만들어 마무리 했습니다.

• https://docusaurus.io/docs/markdown-features/plugins
• https://docusaurus.io/docs/markdown-features/react

그 외

그 외에도, disqus 연동이나 경로를 동일하게 잡아주는 등의 자잘한 작업도 있었습니다. 경로 같은 경우는 hexo를 사용할때 년/월/일/prelink를 적용했었는데 docusaurus에서는 아직 관련 기능을 제공하지 않아, slug를 이용하거나 디렉토리 구조를 변경하면 동일하게 가능합니다.

남은 것...

사실 필요없기도 한데, docusaurus에서는 블로그 기능 이외에도 doc 기능이 있어 별도의 문서 페이지를 만들 수 있습니다. 이를 활용해 자기소개라거나 포트폴리오나 등등 별도 페이지를 구성해볼 생각입니다.