Docusaurus으로 블로그 개발 및 마이그레이션 후기

기존에 gatsby-starter-bee 으로 블로그를 운영하면서 아쉬움이 발생했다. 새로운 기회를 찾아 docusaurus 으로 블로그 개발을 마음잡았고 어떻게 디자인하고 바뀌었는지 후기를 공유합니다.

새로운 블로그 개발 계기

저는 평소에 Notion 을 통해 늘 정리를 해오는데 그중 공유할 만한 주제가 보이면 블로그로 내용을 공유하는 편입니다.

링크드인 , 포트폴리오 와 같은 Publie 한 자료에 대해서는 얼추 정리가 되어서 선순환 을 위한 구조가 만들어졌다고 생각이 되는데 개발 블로그 는 아직 정리되지 않은 느낌이 들었습니다.

개인적으로 아쉽다고 느껴지는 기능들이 있었고 이를 개선하고 싶은데 덕지덕지 커스텀 하는 것이 아닌 정형화된 프레임워크(framework) 에서 기능을 붙어나가고 싶다는 니즈가 있었습니다.

아니면 아쉬운 기능을 내가 개발하는 것이 아닌 이미 잘 반들어진 블로그 서비스 를 사용하면 어떨까? 생각도 해보았습니다.

하지만, 블로그 서비스 를 사용하면 운영 비용은 감소할 수 있겠지만 코드 하이라이팅 같은 것들이 부족할 것으로 생각되었고 앞으로 계속 운영할 생각이 있다면 내가 직접 제품을 만들고 운영해 나가는 것이 더 많은 경험을 얻을 수 있다고 생각했습니다.

블로그 라는 것이 매우 특별한 요구사항을 가진 제품 은 아니기에 이미 SEO 최적화 및 블로그 를 위한 기본적인 기능이 포함된 도구 들이 많이 있을 것이라고 생각하고 새롭게 블로그를 개발하자라는 원대한 목표를 잡게 되었습니다.

어떻게 개발할까? (도구 선택)

요구 사항

기본적으로 기존에 gatsby-starter-bee 에서 운영하던 단점을 보강해줄 수 있는 환경 으로 선택하고 싶었습니다.

개인적인 아쉬움은 아래와 같았습니다.

• Header 에 따른 목차 기능이 없음 (TOC)
• 검색 기능이 없음
• 여러 개의 글이 연결된 시리즈 별 분류를 나타내기 어려움

아래의 목적에도 부합하기를 원했습니다.

• React 으로 개발
• 유지보수 가 활발한 프로젝트
• 커스텀 에 대해서 열려있음
• 마크다운 으로 글을 작성할 수 있어야 함

그리고 CI 에서 주기적으로 가공되어야 하는 Blog 특성상 yarn berry 를 사용하면 얼마나 빨라질 수 있는지 궁금해서 yarn berry 도 사용하고 싶었습니다.

Docusaurus 로 결정!

찾던 중 Docusaurus 라는 것을 발견했는데 마음에 쏙 들더군요.

문서 작성을 위해 추상화 도 잘 되어있고 기본적으로 탑재된 UI/UX 가 만족스러워서 적은 커스텀 으로 좋은 블로그 를 만들 수 있겠다는 생각이 들었습니다.

아쉬운 점은 framework 이다 보니 나만의 개성 은 떨어지겠지만 기본적인 퀄리티 가 좋아서 나만의 아이덴티티 를 살릴 수 있도록 커스텀 하자라는 생각을 했습니다.

Docusaurus 의 가장 큰 결정은 태생이 오픈 소스 프로젝트 웹 사이트를 쉽게 구축, 배포 및 유지 관리하기 위한 프로젝트 이기에 개발 블로그 로 운영하기 위한 코드 하이라이팅 기능도 매우 강력하고, 문서화 도 잘 되어있고, 커스텀 을 위한 확장성도 잘 오픈 되어 있다는 것입니다.

Docusaurus 장점

당시 너무 신나서 장점 을 쭉 정리했는데 아래와 같습니다.

내용	비고
기본적인 레이아웃 제공
오픈 소스 라 커뮤니티 가 있고 유지 보수 가 됨
검색 기능 을 붙일 수 있도록 고려 및 문서화되어 있음
docs 의 경우사이드 바 로 아이템 표시 가능
SEO 관련 기본적으로 고려됨
강력한 코드 하이라이팅, 파일 이름 표시 가능, 내가 어떤 코드를 설명하고 있는지 라인 하이라이팅, 코드 복사 기능
강조 기능, 이것도 정말 필요했던 기능입니다. 이런 것이 없어서 죄다 인용구 로 넣어서 처리하고 있었거든요...
Header Link 기능
위로 바로 올라가기 버튼
읽는 시간 유추 표시
탭 기능
라이브 에디터

이외도 너무 많은데 대부분 마크다운 기능 문서를 보면 알 수 있습니다.

더불어 플러그인 기능도 있어 다른 사람이 만들 기능을 손쉽게 붙어서 사용할 수 있습니다.

이런한 것은 React 등 이용해서 만들 수 있기야 하겠지만 기본적으로 제공하고 수정이 열려있는 점은 큰 장점이라고 느껴졌습니다.

설계 및 진행

이전에 운영되고 있던 것을 안전하게 새로운 것으로 안착시키는 것이 제일 중요하기 때문에 마이그레이션 이 문제가 없는지 꼼꼼히 확인이 필요했습니다.

또한, Docusaurus 라는 공통된 플랫폼을 사용하기 때문에 개성(아이덴티티) 가 있어야 된다고 생각하여 리서치 만 1주일 넘게 진행했습니다.

만드는 것에 급급하지 않고 블로그에 들어왔을 때 유용한 UX 도출하고 싶었습니다.

그래서 우선 Docusaurus 의 기능을 이해하기 위해서 공식 문서 도 모두 읽고 PoC 를 꼼꼼히 거쳤습니다.

개인적으로 정말로 내가 PoC 결과대로 만들어진다는 생각에 이 시간을 제일 재미있게 할 수 있었습니다.

Docusaurus 에서 고려할 것

종합해 보니 아래의 정도로 추려졌고 관련해서 어떻게 되는지 찾아보고 설계할 수 있었습니다.

• SEO 최적화는 어떻게 달성되는가? (e.g. og 썸네일 이미지 및 HTML 에 meta 는 어떻게 생성되는가?)
• 댓글 기능은 어떻게 붙어야 하는가?
• 검색 기능은 어떻게 붙어야 하는가?
• URL 은 어떤 구조로 생성되는가?

마이그레이션 작업 진행

gatsby-starter-bee 글 마이그레이션

사실 이 작업이 제일 걱정되었습니다.

기존에 잘 등록된 글이 URL 구조가 변하면서, 혹은 HTML 이 다르게 가공되면서 문제가 생기지 않을까 말이죠

제 개인적으로는 Docusaurus 의 Plugin 인 plugin-client-redirects 를 이용해서 마이그레이션 이전 URL 을 등록하면 잘 처리되지 않을까 생각했습니다.

관련해서는 자세하게 동일 페이지, 다중 URL의 SEO 처리 방식 에 글을 작성해놨습니다.

마이그레이션 작업 을 진행하면서 문제를 만날 수 있었는데 이전 블로그 에서는 /using-recoil-in-next.js 와 같이 .js 으로 끝나는 URL 의 글이 있었습니다.

문제는 Docusaurus 의 Build 가공 물이 {경로}/index.html 으로 만들어져서 경로에 해당하는 디렉터리의 index.html 가 서빙되는 것이 아닌 해당 .js 파일이 없다고 404 가 응답되는 문제가 있었습니다.

그래서 Build 이후 Shell Script 를 통해서 cp ./using-recoil-in-next.js/index.html using-recoil-in-next.js.html 으로 디렉터리가 아닌 파일로 존재하도록 해서 문제를 해결했습니다.

이거 때문에 당시 식은땀을 흘린 기억이 나네요.

velog 글 마이그레이션

gatsby-starter-bee 블로그 운영 전에 velog 에서도 글을 작성한 것이 있어 이참에 이것도 옮길까 했는데 velog 에는 TIL 와 같이 일기장 형식으로 작성한 글도 많고 무엇보다 102개 로 글의 양이 꽤나 많아서 고민이 되었습니다.

velog 당시 시리즈 물	큐 레이션 을 위해 velog 글 Notion 에 정리

그래도 의미가 있는 글도 있어서 Notion 으로 글을 모두 뽑아서 큐 레이션 후 필요한 글만 Blog 에 올리는 방향으로 velog 에서 작성된 글도 마이그레이션 을 완료할 수 있었습니다.

velog 에는 통계 기능이 있어서 마이그레이션 하면서 어떤 글이 인기 있는지 알 수 있었습니다.

이전에 작성된 글을 보면서 추억에 잠길 수 있었네요. 🥺

디자인

나만의 아이덴티티 를 위해서 커스텀 이 가능한 영역에서 여러 시도를 많이 해보았다.

어떠한 경로를 통해 내 블로그에 랜딩 했을 때 이 블로그는 뭔가 다르다, 이런 특징(갬성)이 있구나를 느낄 수 있도록 하면서 글을 읽으면서도 가독성 에 문제가 없도록 어떤 블록(컴포넌트) 를 사용하면 좋을까, 이렇게 했을 때 아쉬운 부분은 없을까?, 글을 작성해 보며 부족한 부분은 잡아내고 컴포넌트 를 제작해 나갔습니다.

좋아요 버튼 목록에 표시할까 말까 고민의 흔적

독립적인 글의 형태를 가지는 블로그 와 연속적인 시리즈 의 글을 분리할까 말까 도 고민하며 디자인을 잡아갔습니다.

이에 대한 내용은 하단에서 기능을 소개하면서 자세히 풀어볼게요!

UI

완성된 블로그에서 특징적인 UI 에 대해서 소개합니다.

하단부터 UI 이외 UX , Feature 으로 섹션 에 따라 모아서 나열했는데 대부분은 Docusaurus 의 swizzling 를 이용해서 제가 커스텀 한 부분들입니다.

모든 페이지에 BTTB 버튼 적용

Docusaurus 에는 오른쪽 하단에 표시되어 최상단으로 올라갈 수 있는 BTTB(BackToTopButton) 컴포넌트 가 있습니다.

docs 에는 기본적으로 적용이 되어있는데 blog 에는 적용되어 있지 않아 기본적으로 적용된 DocPage/Layout 부분은 제거하고 전체적으로 반영되는 Layout 컴포넌트를 통해 모두 적용할 수 있었습니다.

왜 blog 에는 BTTB 가 적용되지 않았는지 Why does BackToTopButton exist only on Docs Page? · Discussion #7516 · facebook/docusaurus 에서 물어보기도 했습니다.

검색 창을 가운데로

VSCode , YouTube , Notion , etc 뭔가 통합된 검색은 중앙 에 있는 것이 이쁘더군요.

기본적으로 오른쪽에 표시되던 검색 창을 가운데로 변경했습니다.

별거 아닐 줄 알았는데 GNB 부분이 이미 Docusaurus 가 할당한 영역들이 많아서 여기를 비집고 들어가 반응형 을 잡느라 애먹었습니다.

Scroll Progress bar 추가

자칫하면 사용자 시선 처리가 분산되는 효과를 나타낼 거 같아 넣을까 말까 고민했지만 그래도 적용된 것이 더 모던한 사이트라는 경험을 받을 수 있을 거 같아 추가했습니다.

UX

방문한 분들에게 하트 표시

제가 가장 공을 많이 드린 UX 디자인입니다.

hits 를 통해서 조회 수 표시와 함께 봐주셔서 감사하다는 의미로 하트 를 표시했습니다.

페이지를 들어오자마자 하트 애니메이션 으로 눈길을 사로잡고 이 특징이 제 블로그를 기억하는데 더 도움이 될 것이라고 생각했습니다.

medium-zoom 을 이용하여 이미지 확대를 쉽게

블로그를 보면서 가장 많이 보게 되는 것이 텍스트 와 이미지 입니다.

개인적으로 이미지 과정이 부드럽지 않으면 글을 읽으면서 불편함이 느껴지더군요.

그래서 medium-zoom 을 이용해서 부드러운 애니메이션과 함께 이미지를 확대할 수 있도록 했습니다.

해당 기능을 구현하면서 만난 이슈로 스크롤에 따라서 GNB 를 숨기도록 되어있는데 GNB 가 medium-zoom 를 이기는 현상이 있어서 z-index 으로 해결할 수 있었습니다.

연속되는 글은 시리즈로 분리

하나의 Article 이 아닌 연속되는 글들이 있습니다.

예시로 VM으로 Server를 구축하고 Docker로 관리하기 , JSP Project 설정부터 배포까지 , aks, github, slack으로 워크플로우 구축하기 가 있습니다.

원래는 각각의 Article 마다 상단에 연결된 글의 링크를 TOC 으로 표시하고 있었는데 일일이 업데이트하는 것도 귀찮고 TOC 만으로는 이 글이 시리즈 글인지 알 수 없다고 생각했습니다.

마침 Docusaurus 에는 docs 라는 기능으로 왼쪽에 Nav 를 표시할 수 있어서 각 글들의 하이어라키 를 나타내기 좋다는 생각을 할 수 있었습니다.

docs 으로 분리하면 Archive , Tag 가 blog 와 따로 관리된다는 점이 아쉬웠지만 제 블로그를 접속했을 때 왼쪽에 Nav 만을 보고 글이 시리즈 글로 이어진다는 것을 한눈에 파악하고 클릭을 유도하는 것이 더 가치 있는 것이라고 생각하여 연속되는 글 은 docs 라는 기능으로 blog 와 따로 분리했습니다.

작성자는 하단에 배치

Docusaurus 는 기본적으로 상단에 작성자 를 표시해 주고 있었는데 이는 커뮤니티 사이트에서 여러 사람의 작성자가 있는 경우 의미가 있는 배치라고 생각했습니다.

저는 개인 블로그 라 작성한 사람은 나 혼자일 것이고 굳이 상단에 표시할 이유는 없다고 생각되었습니다.

또한, 글의 퀄리티가 좋다면 글을 끝까지 읽을 것이고 제일 하단에서 글을 작성한 내 정보를 보여주는 것이 더 좋은 UX 라고 생각하여 하단에 배치하는 것으로 바꿨습니다.

이걸 바꾸면서 모든 페이지에 전역으로 작성자 메타 데이터 를 추가하면 되겠다 생각이 들어 그렇게 처리했습니다.

Feature

Layout Shift 방지 및 썸네일 이미지 불러올 수 있도록

이제 어느 정도 UI/UX 가 잡혀가니 아쉬운 기능 과 퀄리티 가 눈에 들어오기 시작했습니다.

가장 거슬렸던 부분은 이미지 때문에 Layout Shift 현상이 발생하는 것이었는데 이는 📦 plugin-ideal-image 를 사용해서 해결할 수 있었습니다.

PlugIn 이 있어서 손쉽게 해결될 줄 알았지만... ideal-image 와 medium-zoom 를 통합해야 하는 상황이라 이것도 고생 좀 했습니다.

만난 문제들은 아래와 같았습니다.

트러블 슈팅1: docusaurus-plugin-image-zoom 사용 시 중간 이미지부터는 zoom 안되는 현상으로 컴포넌트 제작

위의 영상을 보면 첫 화면에 로드된 이미지는 미디어 줌 이 되지만 하단에 lazy 로드된 것들은 미디어 줌 이 안 되는 것을 확인할 수 있습니다.

이유는 docusaurus-plugin-image-zoom/src/zoom.js 를 보면 onRouteUpdate() 가 되고 .markdown img 만 적용되기 때문입니다.

docusaurus-plugin-ideal-image 를 사용했기 때문에 화면에 표시되기 전까지는 lazy loading 되어 img 가 아닌 svg 으로 표시되고 있기 때문에 docusaurus-plugin-image-zoom 를 이용해서는 미디어 줌 을 적용할 수 없었습니다.

때문에 svg 에서 image 으로 바뀌면 해당 부분만 미디어 줌 을 적용하도록 해야 했으며 ideal-image 와 미디어 줌 이 가능한 컴포넌트 를 새롭게 만들었습니다.

여기서 ideal-image 에서 lazy loading 이 완료되는 onLoad CallBack 이 없어서 구현하는데 머리 좀 싸맸습니다.

저는 imageContainer 를 만들고 하위 자식이 변경 시 onLoad 되었다고 가정하고 미디어 줌 을 적용하도록 만들었습니다.

트러블 슈팅2: @theme/IdealImage 타입 에러

yarn berry 에서만 발생했던 문제로 import Image from "@theme/IdealImage"; 시 관련 컴포넌트가 없다가 에러가 발생했는데 이는 피어 종속성 인 prop-types 가 없어서 발생하던 문제이었습니다.

그래서 import Image from "@docusaurus/plugin-ideal-image/lib/theme/IdealImage"; 시 타입 에러는 표시되지 않았습니다.

근데 매번 저 이상한 경로로 import 를 하기에는 싫기에 @theme/IdealImage 을 제가 직접 끌어와서 처리했습니다.

해당 기능이 가장 블로그 의 본질적인 기능 개선 이었고 사용자가 보기에 모던한 블로그 경험을 제공하는데 중요한 역할을 할 수 있었습니다.

🌟 앵커 가 제대로 작동

before	after

🌟 스크롤 해도 CLS 발생하지 않음: 오른쪽 스크롤 바를 잘 보세요. Page Down 으로 동일하게 내려가는데 레이지 로딩은 계속 불러오면서 스크롤바가 밀리는 것을 볼 수 있습니다.

before	after

🌟 이미지 썸네일 표시

before	after

🌟 네트워크가 느린 경우 선택적으로 다운로드할 수 있도록

after

홈 화면: 인터랙티브 요소(Interactive Elements) 배치

밋밋한 홈 화면보다는 나만의 아이덴티티 를 가지는 화면이 가지고 싶었습니다.

그래서 사용자의 관심을 끌고, 상호작용을 유도하며, 웹사이트에 머무르게 할 수 있도록 agile-ts 를 참고해서 인터랙티브 요소(Interactive Elements) 를 홈 화면에 배치했습니다.

이것을 만들면서 겪은 문제는 인터렉션 기능인 이모지 가 넘어가는 것이 모바일 에서는 간헐적으로 로드되지 않는 것을 보았습니다.

필요한 이미지가 로드되지 않아서 발생한 문제로 확인하고 필요한 이미지를 Preload 하는 방법으로 해결했습니다.

그래도 조금 플리커링 현상 이 있긴 하지만 이전처럼 이미지가 로드가 안되는 문제는 발생하지 않게 되어 일단 여기까지 하고 나중에 더 디테일을 잡으려고 합니다.

before	after

공유 및 좋아요

글 하단에 글이 좋은 경우 Facebook Like 를 클릭하고 손쉽게 공유 할 수 있도록 버튼을 만들었습니다.

Other

• 댓글 기능
• 홈 화면 방명록
• PWA 지원
• 태그 와 같이 이모지 추가 가능한 부분은 이모지 배치
• 준수 사항 기능을 사용해서 더 알록달록 명확해짐
• docusaurus 기본 번역이 이상한 부분 수정
  • 블로그 이전 과 다음 번역이 반대로 되어있음
  • 태그 부분에서 같은 글자가 2번 반복됨

후기

블로그 개발 후기

Docusaurus 라는 Framework 위에서 개발되었지만 나만의 아이덴티티 를 위해서 어떤 UI/UX 를 디자인할 지 고민하는 과정이 재미있고 유익했던 거 같습니다.

단순하고 쉬운 기능일지 모르지만 이것을 고민하고 만드는 것이 쉽지 않다는 것을 느끼고 앞으로 다른 사람의 블로그를 방문하면 어떤 기능과 아이덴티티 가 있는지 중점적으로 살펴볼 수 있을 거 같습니다.

yarn berry 를 쓰면서 패키지 가 압축이 되어있어서 빠른 종속성 복구 가 가능할지는 몰라도 피어 종속성 이 고려되지 않은 패키지 의 경우 찾아다니면서 복구가 어렵다는 것과, 구현 참조 로 실제 코드를 까보는 것들이 생각보다 불편하다는 것도 경험할 수 있었습니다.

그리고 이전에 운영하던 블로그 의 글을 마이그레이션 하면서 SEO 가 어떻게 이뤄지는지도 경험할 수 있었습니다.

SEO 를 이해하고 안 하고 생긴 차이에 대해서 기억나는 것은 글의 첫 문단은 주로 description meta tag 으로 들어가서 검색 결과 의 요약으로 표시되고, Header 는 H1 는 문서에 한 개만 존재해야 하는 것이지 H1 을 여러 개 명시해서 섹션 을 구분하는 것이 이상하다는 것, 등을 알 수 있었습니다.

이러한 구조를 알게 됨으로써 회사 차원에서 보고서를 쓰더라도 어떤 것이 시맨틱 한 것이고, 의미 있는 워딩과 문장인지 고려해서 글쓰기가 가능할 것 같다는 생각을 가질 수 있었습니다.

Docusaurus 사용 후기

문서 작성을 위해서 기본적으로 필요한 컴포넌트 들이 있어서 좋았고 swizzling 으로 손쉽게 커스텀 가능하다는 것도 큰 장점으로 느낄 수 있었습니다.

SEO 도 잘 처리되어 있어서 리버스 로 제가 어떻게 구현되었는지 살펴보면서 알게 된 것도 많았습니다.

Breadcrumbs 까지 검색 엔진 이 인식할 수 있도록 디자인된 것을 보고 퀄리티에 놀랐습니다!

마무리

제품을 개발하는 능력은 프로로써 어떻게 보면 당연한 것 일 수 있습니다.

그다음 중요한 것을 시장에 프로모션 을 통해 알리는 것이라고 생각됩니다. 만든 것을 나만 알고 있으면 예쁜 쓰레기라고 생각됩니다.

뭐가 되었던 유명해지고 사람들이 많이 쓰기 시작해야 서비스 로써 가치 가 창출된다고 생각합니다.

이번 블로그 개발도 개인 프로젝트 로써 여러 기술 경험도 해보았지만 넓은 범위 로는 나를 프로모션 할 수 있는 블로그 가 만들어졌다는 것에도 큰 의의를 가질 수 있는 거 같습니다.

만들 때는 언제 끝나지… 생각이었지만 만들어진 것을 보고 하루에 몇 번씩 방문해서 내가 추가한 디테일을 보며 뿌듯해하는 과정이 프로젝트 를 진행하면서 재밌는 포인트이었던 거 같습니다.

이상 Docusaurus으로 블로그 개발 및 마이그레이션 후기 를 마치도록 하겠습니다. 읽어주셔서 감사합니다.