Astro+Stalight移行メモ

DokuwikiからAstro+Stalightに移行する際のメモ

いろいろすんなりいかなくて珍道中と化している

Astro Starlight: ランダムリダイレクト機能の実装手順

/random/ にアクセスした際、サイト内の別のドキュメントへ自動的にランダムリダイレクトさせる設定手順です。

1. 作成するファイル

まず、リダイレクトのロジックを持つコンポーネントを作成します。

• ファイルパス: src/components/RandomRedirect.astro
• コード内容: 以下の内容をそのまま貼り付けてください。

src/components/RandomRedirect.astro

---
import { getCollection } from 'astro:content';

// docsコレクションから全記事を取得
const docs = await getCollection('docs');

// 自分自身（random）やトップページ（index）を除外してURLリストを作成
const articles = docs.filter(doc => !doc.id.includes('random') && doc.id !== 'index.md');
const links = articles.map(doc => `/${doc.id.replace(/\.(md|mdx)$/, '')}/`);
---

<p>ページを移動しています...</p>

<script define:vars={{ links }}>
  if (links && links.length > 0) {
    // ランダムに1つURLを選択
    const randomLink = links[Math.floor(Math.random() * links.length)];
    // 戻るボタンの無限ループを防ぐため、replaceで遷移
    window.location.replace(randomLink);
  } else {
    // 万が一記事がない場合のフォールバック先
    window.location.replace('/');
  }
</script>

• ファイルパス: src/content/docs/random.mdx
• コード内容:

---
title: ランダムジャンプ
---

import RandomRedirect from '../../../components/RandomRedirect.astro';

<RandomRedirect />

(※ import の相対パス ../../../ は、実際のフォルダ階層に合わせて調整してください。src/content/docs/random.mdx から見た場合、src/components/ は3階層上になります)

2. 実装のポイント

1. 無限ループの防止 (filter) 自身である random へのアクセスを自動で除外しています。これにより、同じページをループし続けるバグを防ぎます。
2. ブラウザの履歴対策 (window.location.replace) 通常のページ遷移（href）ではなく replace を使うことで、遷移後にユーザーが「戻る」ボタンを押した際、再度ランダム遷移が走って元のページに戻れなくなる現象を回避しています。
3. サイドバーへの表示 Starlightの自動サイドバー設定を使用している場合、自動的に「ランダムジャンプ」という項目が追加されます。非表示にしたい場合は、Starlightのサイドバー設定（astro.config.mjs）で手動管理にするか、フロントマターで制御してください。

DokuWikiからAstro Starlightへの画像・ZIPパス移行手順書

DokuWikiからエクスポートし、Pandocで変換したMarkdownファイル内の画像パス（/media/）を、Starlight推奨の配置に合わせて修正する手順です。 ※ZIPなどの配布ファイルは public/ の絶対パスを維持し、画像のみを src/assets/ の相対パスへ書き換えます。

---

📂 1. 事前準備：ファイルの配置

DokuWikiの /media フォルダ内を、拡張子（ファイル種別）ごとに以下のように分けて配置します。

• 画像ファイル（PNG, JPG, WebPなど） 👉 src/assets/media/ に配置
• 配布用ファイル（ZIP, PDFなど） 👉 public/media/ に配置

---

🛠 2. 移行手順（MSYS2環境での実行）

作業はすべて、Starlightのドキュメントルートである src/content/docs/ ディレクトリに移動した状態 で実行します。

ステップ 1：トップ直下の記事（docs/*.md）の処理

① 置換対象の確認（プレビュー）

まずは以下のコマンドを実行し、置換対象となる画像パスが正しく抽出されるか画面で確認します。

grep "(\/media\/" *.md

※もしこの中にZIPファイル（.zip）が含まれている場合は、目視でメモしておきます。

② プレビュー確認付きで置換を実行

以下のコマンドを実行します。実行すると、書き換え後の内容が画面に表示されます。 問題がなければ、末尾に > 置換後ファイル名 を指定するか、-i オプションを付けて実行してください。

確認用（画面に出力）：

sed 's|(\/media\/|(\.\./\.\./assets/media/|g' *.md

確定用（ファイルを上書き保存）：

sed -i 's|(\/media\/|(\.\./\.\./assets/media/|g' *.md

③ 【重要】ZIPファイルのパスを絶対パスに戻す

画像と一緒にZIPのパスも書き換わってしまった場合、以下のコマンドで元の絶対パス（/media/...）に戻します。

sed -i 's|(\.\./\.\./assets/media/\(.*\.zip\))|(/media/\1)|g' *.md

---

ステップ 2：カテゴリ階層の記事（docs/category/*.md）の処理

※ category 部分は、実際のカテゴリフォルダ名に置き換えて実行してください。

① 置換対象の確認（プレビュー）

grep "(\/media\/" category/*.md

② 確定用コマンドの実行（上書き保存）

カテゴリ階層は1段深いため、戻る相対パス（../）が1つ多くなります。

sed -i 's|(\/media\/|(\.\./\.\./\.\./assets/media/|g' category/*.md

③ 【重要】ZIPファイルのパスを絶対パスに戻す

sed -i 's|(\.\./\.\./\.\./assets/media/\(.*\.zip\))|(/media/\1)|g' category/*.md

---

📊 3. 変換前後の期待値チェック

作業完了後、Markdownファイル内の記述が以下のようになっているか、最終確認してください。

記事の場所	ファイルの種類	変換前の状態（Pandoc直後）	変換後の状態（期待値）
トップ直下	画像		
トップ直下	ZIP	[DL](/media/file.zip)	[DL](/media/file.zip)（絶対パスのまま維持）
カテゴリ内	画像		
カテゴリ内	ZIP	[DL](/media/file.zip)	[DL](/media/file.zip)（絶対パスのまま維持）

確認コマンドとして git diff を実行し、緑色（追加行）のパスが上記と一致していれば移行成功です！

pandocで変換したgfm markdownにAstro+Stalight等で認識できるタイトル表記を付ける

変換前

# YAMAHA XGソフトウエア音源を x64 環境で使えるようにする

変換後

---
title: YAMAHA XGソフトウエア音源を x64 環境で使えるようにする
---

変換スクリプト

対象のルートフォルダに cd で移動して以下を実行してください。

bash replace_title.sh

replace_title.sh

# 子フォルダの再帰検索（**）を有効化

shopt -s globstar

# ループ処理の開始
for file in **/*.md; do
    # ファイルが実際に存在すること、かつ通常のファイルであることを確認
    [ -f "$file" ] || continue

    # 1行目が「# 」で始まっているか確認
    if head -n 1 "$file" | grep -q '^# '; then
        echo "処理中: $file"

        # 1行目のみをFrontmatter形式に置換（文字コードはUTF-8を維持）
        sed -i '1s/^# \(.*\)/---\ntitle: \1\n---/' "$file"
    fi
done

# 設定を元に戻す（一応のクリーンアップ）
shopt -u globstar
echo "すべての一括置換処理が完了しました。"