[Astro] トラブルシューティングとTips

概要

前回の記事ソーシャル共有自動化スクリプトでソーシャルメディア共有の自動化を解説しました。シリーズ最終回となる今回のポストでは、JekyllからAstroへのマイグレーション中に遭遇した問題とその解決方法、そして役立つTipsをまとめます。

マイグレーションを進めていると、公式ドキュメントでは扱っていない予想外の問題に遭遇することがあります。この記事が同様の経験をされる方の時間を節約できれば幸いです。

モバイルの横スクロール問題

問題

マイグレーション後、デスクトップでは問題なく表示されていたサイトが、モバイルで左右にスクロールできてしまう問題が発生しました。テストをデスクトップブラウザ中心に行っていたため、しばらく発見できませんでした。

原因

元々<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の両方に設定しないとモバイルで微妙な横スクロールが残ることがあるので注意が必要です。

追加Tips：日本語の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との比較

2つの方式の違いをまとめると以下の通りです。

項目	Jekyll (Rouge)	Astro (Shiki)
動作方式	ビルド時にHTML + CSSクラスを生成	ビルド時にinlineスタイルを適用
テーマ適用	CSSファイルを別途管理	設定でテーマ名を指定するだけ
対応言語	Ruby Gemに依存	VS Code互換の文法ファイルを使用
設定の複雑さ	`_config.yml` + CSSファイル	`shikiConfig.theme`の一行

Shikiはinlineスタイルを使用するためCSSファイルの競合の心配がなく、VS Codeで見るのと同じレベルの構文ハイライトを提供します。

rehype-calloutsでコールアウトを実装

ブログ記事を書いていると「参考」「注意」「Tips」のような強調ブロックが必要な時があります。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]
> 役立つTipsをここに書きます。

> [!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"：リファラー情報を渡さずセキュリティが向上します

内部リンク（/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自動共有
トラブルシューティングとTips

JekyllからAstroへのマイグレーションは単にビルド速度を改善するために始めましたが、結果的に開発体験全般が大きく向上しました。TypeScriptサポート、ViteベースのHMR、柔軟なマークダウンプラグインシステム、そして現代的なNode.jsエコシステムとの統合は、ブログ運営をはるかに楽しくしてくれました。

マイグレーションが常に簡単なわけではありません。既存コンテンツの変換、URL維持、多言語対応など気を配る必要があることが多くありました。しかし一度完了すれば、その後のブログ運営がはるかに楽になります。

このシリーズがJekyllからAstroへのマイグレーションを検討されている方に少しでもお役に立てれば幸いです。