[Astro] 트러블슈팅과 팁

개요

이전 글 소셜 공유 자동화 스크립트에서 소셜 미디어 공유 자동화를 다루었습니다. 시리즈의 마지막 글인 이번 포스트에서는 Jekyll에서 Astro로 마이그레이션하면서 겪었던 문제들과 해결 방법, 그리고 유용한 팁들을 정리합니다.

마이그레이션을 하다 보면 공식 문서에서 다루지 않는 예상치 못한 문제들을 만나게 됩니다. 이 글이 비슷한 경험을 하시는 분들에게 시간을 절약해드리길 바랍니다.

모바일 좌우 스크롤 문제

문제

마이그레이션 후 데스크톱에서는 문제없이 보이던 사이트가, 모바일에서 좌우로 스크롤이 되는 문제가 발생했습니다. 테스트를 데스크톱 브라우저 위주로 했기 때문에 한동안 발견하지 못했습니다.

원인

원래 <body>에만 overflow-x: hidden을 설정해두었는데, 일부 모바일 브라우저(특히 모바일 Safari와 일부 Android 브라우저)에서는 이것만으로는 좌우 스크롤을 완전히 방지하지 못합니다. <html> 요소에도 함께 설정해야 합니다.

해결

src/styles/global.scss에서 <html> 요소에도 overflow-x: hidden을 추가하여 해결했습니다.

/* src/styles/global.scss */
html {
  overflow-x: hidden;
}
body {
  margin: 0;
  overflow-x: hidden;
  word-break: break-word;
  letter-spacing: 0.8px;
  background-color: #f6f8fa;
}

간단한 수정이지만, html과 body 모두에 설정하지 않으면 모바일에서 미묘한 좌우 스크롤이 남을 수 있으니 주의가 필요합니다.

추가 팁: 일본어 word-break

일본어 콘텐츠에서는 줄바꿈이 제대로 되지 않는 문제가 있었습니다. 일본어는 띄어쓰기가 없기 때문에 break-word만으로는 적절한 줄바꿈이 이루어지지 않습니다. :lang(ja) 선택자로 별도 설정을 적용하여 해결했습니다.

/* src/styles/global.scss */
:lang(ja) body {
  word-break: break-all;
}

Sass Deprecation 경고

문제

Jekyll에서 사용하던 SCSS 파일을 가져와서 빌드하니, deprecation 경고가 대량으로 출력되었습니다.

DEPRECATION WARNING: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.
DEPRECATION WARNING: Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0.

해결

이상적으로는 @import를 @use/@forward로, darken()을 color.adjust()로 변환하는 것이 좋지만, 기존 SCSS 코드량이 많아 당장은 현실적이지 않았습니다. 우선 astro.config.mjs의 vite 설정에서 경고를 무시하고, 점진적으로 새 문법으로 전환하기로 했습니다.

// astro.config.mjs
vite: {
  css: {
    preprocessorOptions: {
      scss: {
        silenceDeprecations: ['import', 'global-builtin', 'color-functions'],
      },
    },
  },
},

각 deprecation의 의미는 다음과 같습니다.

Deprecation	설명
`import`	`@import` 대신 `@use`/`@forward` 사용 권장
`global-builtin`	전역 함수 대신 모듈 함수 사용 권장 (`darken()` → `color.adjust()`)
`color-functions`	색상 관련 함수의 인터페이스 변경

Shiki 코드 하이라이팅

Jekyll과의 차이

Jekyll에서는 Rouge라는 Ruby 기반 코드 하이라이터를 사용했고, CSS 파일을 별도로 관리해야 했습니다. Astro는 Shiki를 내장하고 있어 별도 설치나 CSS 파일 없이 코드 하이라이팅이 동작합니다.

설정

astro.config.mjs에서 테마만 지정하면 됩니다. 저는 어두운 배경의 material-theme-darker를 사용하고 있습니다.

// astro.config.mjs
markdown: {
  shikiConfig: {
    theme: 'material-theme-darker',
  },
},

Jekyll Rouge와의 비교

두 방식의 차이를 정리하면 다음과 같습니다.

항목	Jekyll (Rouge)	Astro (Shiki)
동작 방식	빌드 시 HTML + CSS 클래스 생성	빌드 시 inline 스타일 적용
테마 적용	CSS 파일을 별도 관리	설정에서 테마명만 지정
지원 언어	Ruby Gem에 의존	VS Code 호환 문법 파일 사용
설정 복잡도	`_config.yml` + CSS 파일	`shikiConfig.theme` 한 줄

Shiki는 inline 스타일을 사용하므로 CSS 파일 충돌 걱정이 없고, VS Code에서 보는 것과 동일한 수준의 구문 강조를 제공합니다.

rehype-callouts로 콜아웃 구현

블로그 글을 쓰다 보면 “참고”, “주의”, “팁” 같은 강조 블록이 필요할 때가 있습니다. rehype-callouts 플러그인을 사용하면 GitHub 스타일의 콜아웃 블록을 마크다운에서 간단히 사용할 수 있습니다.

설치와 설정

npm install rehype-callouts

// astro.config.mjs
import rehypeCallouts from 'rehype-callouts';

markdown: {
  rehypePlugins: [
    [rehypeCallouts, { theme: 'github' }],
  ],
},

사용법

마크다운에서 blockquote 안에 [!NOTE], [!TIP], [!WARNING] 등의 키워드를 넣으면 됩니다.

> [!NOTE]
> 참고할 내용을 여기에 작성합니다.

> [!TIP]
> 유용한 팁을 여기에 작성합니다.

> [!WARNING]
> 주의할 내용을 여기에 작성합니다.

GitHub README에서 보던 것과 동일한 스타일의 콜아웃 블록으로 렌더링됩니다. theme: 'github'을 설정했기 때문에 색상과 아이콘이 GitHub 스타일로 표시됩니다.

rehype-external-links로 외부 링크 처리

블로그 글에는 외부 사이트 링크가 자주 포함되는데, 보안과 SEO를 위해 외부 링크에는 target="_blank"와 rel="nofollow noreferrer"를 추가하는 것이 좋습니다. 하지만 매번 마크다운에서 HTML을 직접 작성하는 것은 번거롭습니다.

rehype-external-links 플러그인을 사용하면 외부 링크에 이 속성들을 자동으로 추가할 수 있습니다.

설정

// astro.config.mjs
import rehypeExternalLinks from 'rehype-external-links';

markdown: {
  rehypePlugins: [
    [rehypeExternalLinks, { target: '_blank', rel: ['nofollow', 'noreferrer'] }],
  ],
},

효과

마크다운에서 평소대로 외부 링크를 작성하면:

[Astro 공식 사이트](https://astro.build)

빌드 시 자동으로 다음과 같이 변환됩니다:

<a href="https://astro.build" target="_blank" rel="nofollow noreferrer"
  >Astro 공식 사이트</a
>

target="_blank": 새 탭에서 열기. 외부 링크를 클릭해도 현재 블로그 페이지가 유지됩니다
rel="nofollow": 검색 엔진에 링크 가중치를 전달하지 않습니다
rel="noreferrer": 리퍼러 정보를 전달하지 않아 보안이 향상됩니다

내부 링크(/ko/astro/...)에는 적용되지 않고 외부 링크(https://...)에만 자동으로 적용되므로, 신경 쓸 것 없이 평소대로 마크다운을 작성하면 됩니다.

마이그레이션 시 주의점

Jekyll에서 Astro로 마크다운 파일을 옮기면서 주의해야 할 점들을 정리합니다.

1. permalink 형식

Jekyll에서는 _config.yml의 permalink 설정으로 URL이 자동 생성되지만, Astro에서는 각 포스트의 frontmatter에 명시적으로 지정해야 합니다. 기존 URL을 유지하려면 Jekyll에서 사용했던 URL 패턴을 그대로 작성해야 합니다.

# Jekyll: _config.yml에서 패턴으로 자동 생성
permalink: /:categories/:title/

# Astro: 각 포스트 frontmatter에 직접 지정
permalink: /astro/installation/

2. 날짜 처리

Jekyll에서는 frontmatter의 날짜를 자동으로 파싱하지만, Astro의 Zod 스키마에서는 z.coerce.date()를 사용해야 문자열 날짜를 Date 객체로 변환할 수 있습니다. z.date()를 사용하면 문자열을 받아들이지 않아 에러가 발생합니다.

// src/content.config.ts
// z.date()는 Date 객체만 허용 — 문자열 날짜에 에러 발생
// z.coerce.date()는 문자열도 Date로 자동 변환
date: z.coerce.date(),

3. published 필드

Jekyll에는 없던 published 필드를 추가했습니다. default(true)로 설정하면 기존 포스트에 published 필드가 없어도 자동으로 공개 상태가 됩니다. 초안은 published: false를 명시하면 빌드에서 제외됩니다.

// src/content.config.ts
published: z.boolean().default(true),

4. 이미지 경로

Jekyll에서 사용하던 이미지 경로를 그대로 유지하려면, public/ 디렉토리에 동일한 구조로 이미지를 배치합니다. public/의 파일은 빌드 시 dist/로 그대로 복사되므로, URL이 변경되지 않습니다.

# Jekyll: _site/assets/images/...
# Astro:  public/assets/images/... → dist/assets/images/...

5. Liquid 태그 제거

Jekyll의 Liquid 태그({% raw %}{% include %}{% endraw %}, {% raw %}{{ }}{% endraw %} 등)는 Astro에서 처리되지 않으므로 마크다운에서 제거하거나 대체해야 합니다.

{% raw %}{% include in-feed-ads.html %}{% endraw %} →  (rehype-in-feed-ads 플러그인이 처리)
{% raw %}{{ site.url }}{% endraw %} → URL을 직접 작성하거나 컴포넌트에서 처리

최종 성능 비교

시리즈를 마무리하면서, 마이그레이션 전후의 전체적인 비교를 정리합니다.

항목	Jekyll	Astro
전체 빌드 시간	~209초	~30초
개발 서버 시작	~50초 (최적화 후)	~2초
파일 수정 반영	전체 리빌드	HMR 즉시 반영
런타임 의존성	Ruby, Bundler, Gem	Node.js, npm
타입 안전성	없음	TypeScript + Zod
이미지 최적화	플러그인 의존	Sharp 기반 커스텀 플러그인
코드 하이라이팅	Rouge + CSS 파일	Shiki (inline 스타일)
검색	커스텀 JSON 기반	Pagefind (WebAssembly)
사이트맵	플러그인	@astrojs/sitemap
RSS	플러그인	@astrojs/rss
댓글	Utterances (동일)	Utterances (동일)

숫자로 보면 빌드 속도가 약 7배 빨라진 것이 가장 눈에 띄지만, 실제로 가장 체감이 큰 변화는 개발 서버입니다. 글을 수정하고 50초를 기다리던 시절과 비교하면, 저장 즉시 반영되는 HMR은 정말 혁신적입니다.

시리즈를 마치며

이 시리즈를 통해 Jekyll에서 Astro로의 마이그레이션 전체 과정을 공유했습니다. 전체 시리즈를 정리하면:

Jekyll에서 Astro로 마이그레이션한 이유 — 빌드 속도 문제와 Astro 선택 배경
Astro 설치 및 프로젝트 구성 — 프로젝트 설정과 디렉토리 구조
Content Collections와 마크다운 마이그레이션 — Zod 스키마와 콘텐츠 관리
다국어(i18n) 구현 — 3개 언어 지원 시스템
SEO 구현 — 메타 태그, JSON-LD, 사이트맵
이미지 최적화 — 커스텀 rehype 플러그인
댓글 시스템 (Utterances) — GitHub Issues 기반 경량 댓글
광고 연동 (Google AdSense) — AdSense 연동과 rehype 플러그인
Pagefind를 이용한 검색 구현 — 정적 검색 기능
레이아웃과 컴포넌트 아키텍처 — 컴포넌트 설계
GitHub Pages 배포 — 빌드와 배포 파이프라인
소셜 공유 자동화 스크립트 — SNS 자동 공유
트러블슈팅과 팁

Jekyll에서 Astro로의 마이그레이션은 단순히 빌드 속도를 개선하기 위해 시작했지만, 결과적으로 개발 경험 전반이 크게 향상되었습니다. TypeScript 지원, Vite 기반 HMR, 유연한 마크다운 플러그인 시스템, 그리고 현대적인 Node.js 생태계와의 통합은 블로그 운영을 훨씬 즐겁게 만들어 주었습니다.

마이그레이션이 항상 쉬운 것은 아닙니다. 기존 콘텐츠 변환, URL 유지, 다국어 대응 등 신경 써야 할 것이 많았습니다. 하지만 한 번 완료하고 나면 그 이후의 블로그 운영이 훨씬 편해집니다.

이 시리즈가 Jekyll에서 Astro로 마이그레이션을 고려하시는 분들에게 조금이나마 도움이 되었으면 합니다.