Astro로 사이트를 옮겼습니다!

2024-12-29

만약 이 블로그 글을 읽고 계신다면, Astro 기반의 새로운 사이트를 읽고 있습니다!

공지사항

새로운 사이트로 전환하면서 알고 계셔야 할 중요한 사항만 나열하겠습니다:

전환하는 동기

사용해본 웹사이트 프레임워크가 하도 많아서 기억하기조차 어렵습니다. 예전에 WordPress, Ghost, 그리고 Jekyll 등을 사용하다가 마침내 2021년에 Hugo에 정착했습니다. 마지막 두 프레임워크는 GitHub Pages를 호스팅으로 사용했는데, 학생으로선 무료가 제일 좋거든요.

Hugo를 선택했을 때, 앞으로 몇 년은 사이트를 이대로 유지할 생각이었습니다. 전체적으로 봤을때 웹사이트는 괜찮았지만, 몇 가지 아쉬운 점들이 있었습니다.

일단, 디자인을 하도 못해서 (아직도 못하지만), 당시에 이미 만들어진 anatole이란 테마를 사용했습니다. 쓸 수 있게 배포해 주셔서 너무 감사했지만, 제가 기반해서 만든 사이트가 제가 만든 것처럼 느껴지지 않았고, 아무리 스타일을 변경해봐도 변함이 없었습니다.

스타일 변경을 얘기해서 말인데, Hugo로 스타일링을 하는 게 꽤 어려웠습니다. Hugo는 구글의 Go 언어를 기반으로 작성되어 있는데, 추가로 배워야 하는 독자적 템플릿 문법이 있습니다. 사소한 변경을 할 때마다 이 문법을 배워야 된다는 점이 사이트를 바꾸는데 큰 애로사항이 되어버려, 사이트 자체 디자인이 꽤 오랫동안 방치되어 왔죠.

하지만 Markdown 파일을 작성하고 커밋하여 GitHub에 올리는 것만으로 블로그 글을 작성할 수 있다는 점이 좋았습니다. 게다가 Hugo하고 제가 쓰던 anatole 테마는 번역 기능(i18n)을 잘 지원했는데, 저는 블로그 글을 영어로도 쓰기 때문에 꼭 필요로 하는 기능이었습니다. 너무 쓰기 간편해서, 사실 2021-23년 군대에 복역할 때도 아이패드 상 Working Copy라는 어플로 Markdown 파일을 작성하고 GitHub에 올려 블로그에 계속 글을 올릴 수 있었습니다.

그러나 최종적으로 이전을 선택한 이유는 기존 사이트에 JavaScript를 추가하는 것이 너무 어려워서였습니다. 사이트에 여러 도구들을 만들어 뒀는데, 만들때마다 그냥 JS를 <script> 태그들 안에 집어넣고 Hugo가 Markdown 파일 안 HTML을 렌더링하도록 설정했습니다. (강제하는 설정값이 쓸데없이 무서운 unsafe로 시작하게 만들어뒀는데 무슨 생각인지 싶습니다.) 하지만 도구들과 페이지들의 크기와 범위가 넓어지자 더 많은 기능과 의존 패키지를 추가해야 됬는데, 그럴려면 JS 번들러(bundler)를 사용해서 JS를 최종 형태로 컴파일해야 하죠.

문제는 이게 Hugo에 내장된 기능이 아니기 때문에, webpack을 추가로 붙여놓아 JS를 컴파일해야 됐습니다. 어느 정도 괜찮게 작동하긴 했지만, 빌드 과정이 더욱 더 복잡해진다는 단점이 있었습니다. 더 큰 문제는 소스 코드를 어떻게 정리할지, 그리고 정리한 후 webpack이 이를 Hugo가 사용할 수 있는 번들 파일로 깨끗하게 컴파일하는 방법을 찾지 못했습니다. 게다가 위에서 설명했듯이 수정을 할 때마다 템플릿 언어를 배워야 한다는 점 때문에 결국 다른 프레임워크를 사용하기로 결정했습니다.

첫 선택: NextJS

예전에 만든 개인 프로젝트와 대학 프로젝트에서 NextJS를 사용해본 적이 있어, 이번에 새로 사이트를 만들 때도 유용할 거라 생각했습니다.

아쉽게도, 약 40% 이전을 마친 상태에서 NextJS의 내장 MDX 컴파일러가 사진 파일을 상대 경로로 불러올 수 없다는 것을 알게 됐습니다. next-mdx-remote 또한 이 기능을 지원하지 않았고요. 이게 왜 문제가 되냐면, 이미 Markdown으로 작성한 블로그 글이 많이 있는데 (정확히는 67개 — 영어 번역을 포함해서 134개), 각 글마다 이렇게 정리해두었기 때문입니다:

blog/
  2024/
    2024-12-29-i-migrated-my-site-to-astro/
      en.mdx
      ko.mdx
      imgA.png

상대 경로로 사진을 불러올 수 없다면 다음과 같은 코드를 ko.mdx에 작성할 수가 없죠:

import imgA from './imgA.png';

Astro로 사이트를 이전했습니다:

<Image src={imgA}>

대책 해결방안은 폴더 속 모든 사진들을 public/ 폴더로 옮기는 것이었는데, 이를 매번 하는 것도 번거롭고 정리가 되지 않아 이렇게 진행하고 싶지는 않았습니다.

mdx-bundler는 상대 경로 불러오기를 지원하는 듯 했는데, 빌드 과정 중 별다른 번들러를 추가로 설치하는 것을 필요로 했고, 이미 Hugo와 webpack 때문에 이전하는 건데 왜 굳이 이렇게 해야 하나 싶었습니다.

이렇게 애로사항을 겪고 있을 때, Purdue Hackers (제가 다니는 퍼듀 대학교의 개발 동아리) Discord에 물어보니 가장 많이 나온 추천이 Astro였습니다. 그래서 익숙한 프레임워크를 사용할 수 없음에도 불구하고 다음으로 Astro를 한번 사용해보기로 했습니다. 아마도 Astro가 더 좋을 수도 있겠죠?

(스포: 더 좋죠. 왜냐하면 이 블로그 글을 읽고 있으니까요)

매끄럽지 못한, 사이트 전환 시작

그래서 11월 29일경 사이트 이전을 시작했으니, 전부 전환해 오는데 약 한 달이 걸렸네요. 그런데 왜 이리 오래 걸렸는지 좋은 이유를 댈 수 있습니다.

일단 이전을 시작하기 전, 스스로를 위해 정해둔 몇 가지 요구사항들입니다:

시작하기도 무섭게, 바로 문제가 생겨버렸습니다. Astro가 이전 URL인 https://ericswpark.com/ko/blog/index.xml에선 RSS 피드를 렌더링하는 것을 거부했거든요. 그래서 바로 버그 리포트를 접수했는데, 이번 주 전까지는 아무런 답변이 없었습니다. Astro 대표 개발자들과 대화를 나눈 끝에, 버그가 어디에서 발생되는지 알아내어 pull request를 따로 열었습니다. Astro Discord 서버 상에선 개발자가 이를 확인해주겠다고 했는데, 이 글을 쓰는 시점에도 아직까지 패치되지 않았습니다. 하지만 patch-package로 패치할 수 있고 나중에 통합이 되면 그냥 패치를 제거하면 되니 크게 문제될 건 없습니다.

만들다가 요구사항 2번은 조금 덜 빡빡하게 해도 괜찮을 것 같아 URL을 index.xml에서 rss.xml로 바꿨습니다. 더 적절해 보이고, 나중에 JSON 형식 (rss.json)처럼 다른 포맷도 추가할 수 있기 때문이죠.

기말고사 기간이 끝나고 나서 사이트 마이그레이션에 계속 매달렸습니다. 거의 대부분을 처음부터 다시 작성해야 되서 시간이 좀 오래 걸렸습니다. Github Gist 임베드 등을 위한 컴포넌트를 작성해야 했고, 스타일링은 CSS로 만들었으며 (이때 Tailwind CSS가 도움이 많이 됐죠), 라우팅 — 특히 번역 라우팅을 제가 원하는 대로 일일히 설정해야 했습니다.

근데 그걸 다 만든다면…?

좋은 것들만 모여 있는 곳

Astro가 정말 좋은 게, 생각할 수 있는 거의 모든 것이 기본으로 지원된다는 점입니다. MDX로 작성하고 싶다고요? Astro에선 지원하죠. 코드 문법 하이라이팅을 원하신다고요? Astro에선 지원하죠. Tailwind CSS? 지원한다고요. React 추가? 당연하죠. Vue도 같이? 왜 안되겠어요. 서버쪽 렌더링? 옵션값만 바꾸면 되죠. 정적 사이트 렌더링? 이미 기본값입니다. 사용설명서도 충실하고 .astro 파일은 그냥 JS에 frontmatter와 비슷한 부분을 추가해서 연장한 것에 불과하기 때문에, 프레임워크에 익숙해지는데 그리 많이 걸리지도 않았습니다.

그리고 CSS를 처음부터 작성하였기에, 사이트를 더욱 더 유연하고 자유롭게 원하는 대로 변경할 수 있었습니다. (그렇게 얘기하지만 아직도 디자인 감각이 없는게 문제죠. 홈페이지는 그래도 예쁘다고 해주세요.) 또 Astro는 스타일링 규칙이 서로 충돌하지 않도록 분리된 스타일링 기능도 있어 매우 편했습니다. 물론, 전역 스타일이 가끔씩 문제를 일으켜서 피곤하게 하는 경우도 있지만, 그럴 때는 그냥 스타일링 규칙을 구체적으로 지정해주면 아예 문제를 피할 수 있죠.

그리고 처음으로 마이그레이션을 시작할 때 겪은 문제를 제외하면 나머지는 너무 매끄럽게 진행되었고, 원했던 모든 요구사항들을 충족할 수 있었습니다.

비교하기

만약 궁금하시다면 예전 사이트와 새 사이트를 비교하는 사진들을 확인해보세요:

이전 홈페이지 (라이트 모드)새 홈페이지 (라이트 모드)
이전 블로그 글 예시 (라이트 모드)새 블로그 글 예시 (라이트 모드)

특정하자면 다음 부분들이 가장 마음에 듭니다:

물론, 사이트는 추후해도 계속 개선할 예정입니다. 하지만 일단 가장 큰 마이그레이션이 끝났으니까, 드디어 작성을 미루고 있던 블로그 글들에 다시 집중할 수 있게 됐습니다.

그게 전부입니다!

새 사이트가 마음에 드셨으면 좋겠습니다! 만약 제안이나 피드백이 있으시면 이메일을 통해 연락주세요. 특히 존재하지 않는 링크가 있다면 제보해 주시면 감사하겠습니다. (죽은 링크를 하도 싫어해서 다 가져왔다고 확신하지만)

그리고 이번 마이그레이션을 기회로 사이트에 조그만 이스터 에그를 숨겨뒀습니다. 개인적으로 귀여운 것 같아요. 만약 찾으시면 이메일이나 Discord로 알려주세요! (사이트 하단 부분 글귀 아닙니다.)