Astroでシンプルなサイトを作る

src/
├─ assets/ # faviconなどの静的なアセット
├─ components/ # Reactコンポーネント、Astroコンポーネント
├─ content/ # 執筆記事
├─ integrations/ # build時に走らせるスクリプト
├─ layouts/ # ヘッダーやフッターなどページ間で共有される共通UI
├─ pages/ # ルーティング
├─ styles/ # 全体に適応するスタイル
└─ utils/ # その他（remark処理、React hooks、汎用関数など）

---
import { type CollectionEntry, render } from "astro:content";
import type { CollectionKey } from "astro:content";

// 1. MappingしたいUIコンポーネントをインポート
import {
  Heading,
  CodeBlock,
  // ...
} from "../components/content/index.astro";

interface Props<T extends CollectionKey> {
  entry: CollectionEntry<T>;
}

const { entry } = Astro.props as Props<CollectionKey>;
const { Content } = await render(entry);

// 2. マッピング対象のタグとUIコンポーネントをマッピング
const components = {
  h2: Heading,
  h3: Heading,
  h4: Heading,
  pre: CodeBlock,
  // ...
};
---

<Layout ...>
  <article>
    <!-- ... -->
    <!-- 3. Contentのcomponentsにマッピングしたコンポーネントのオブジェクトを渡す -->
    <Content components={components} />
    <!-- ... -->
  </article>
</Layout>

https://slimalized.dev/posts/build-astro-site#見出しにアンカーリンクをつける

---
// h2 にマッピングするコンポーネント

const { id } = Astro.props; // id = "a-bc-d" 
const pageUrl = // ページのURL
---

<h2>
  <!-- アンカーリンクは付与できた。 -->
  <a href={`${pageUrl}#${id}`}>#</a> 
  <!-- ここに見出しテキスト「a BC d」を入れたい。
       しかし、idの値（a-bc-d）しか参照できない。 -->
</h2>

import type { Heading, Node, Root } from "mdast";
import type { Plugin } from "unified";
import { inspect } from "unist-util-inspect";
import { type Visitor, visit } from "unist-util-visit";

const visitor: Visitor<Heading> = (node, index, parent) => {
  // ここに実行する処理を記述する
};

export const headingAnchor: Plugin<[], Root> = () => {
  return (tree: Node) => {
    // console.log(inspect(tree)); // MDASTの表示
    visit(tree, "heading", visitor);
  };
};

import type { Heading, Node, Root, Text } from "mdast";
import type { Plugin } from "unified";
import { type Visitor, visit } from "unist-util-visit";
import { inspect } from "unist-util-inspect";

export interface HeadingProps {
  value?: string;
  id: string;
}

const visitor: Visitor<Heading> = (node, index, parent) => {
  if (parent === undefined || index === undefined) return;

  const heading: Heading = {
    data: {
      hProperties: {
        value: (node.children[0] as Text).value, // hPropertiesを通して、Astro.propsから見出しテキストを参照できるようになる
      } satisfies Pick<HeadingProps, "value">,
    },
    ...node,
  };

  parent.children.splice(index, 1, heading); // 現在のノードを置き換える
};

export const headingAnchor: Plugin<[], Root> = () => {
  return (tree: Node) => {
    visit(tree, "heading", visitor);
  };
};

---
// h2 にマッピングするコンポーネント

const { id, value } = Astro.props; // id = "a-bc-d", value = "a BC d"
const pageUrl = // ページのURL
---

<h2>
  <a href={`${pageUrl}#${id}`}>#</a> 
  {value}
</h2>

console.log("Hi!");

```js hi.js
console.log("Hi!");
```

import type { Code, Parent, Root } from "mdast";
import type { Plugin } from "unified";
import type { Node } from "unist";
import { type Visitor, visit } from "unist-util-visit";

export interface CodeBlockProps {
  lang: string;
  title?: string;
  code: string;
}

const visitor: Visitor<Code> = (node, index, parent) => {
  if (!parent || index === undefined) {
    return;
  }

  const { lang, meta, value } = node;
  const title = meta;

  const code: Parent = {
    type: "pre",
    data: {
      hName: "pre",
      hProperties: {
        code: encodeURIComponent(value),
        ...(lang ? { lang } : { lang: "text" }),
        ...(title ? { title } : {}),
      } satisfies CodeBlockProps,
    },
    children: [],
  };

  parent.children.splice(index, 1, code);
};

export const codeBlock: Plugin<[], Root> = () => {
  return (tree: Node) => {
    visit(tree, "code", visitor);
  };
};

---
import { Code } from 'astro:components';
---
<Code
  lang="js"
  code={`console.log("hello world!");`}
  themes={{ light: "github-light", dark: "github-dark" }} {/* ライトモード・ダークモードでテーマを切り替える */}
/>

---
import { Code } from "astro:components";
import { nanoid } from "nanoid";
import type { BuiltinLanguage, LanguageRegistration, SpecialLanguage } from "shiki";
import type { CodeBlockProps } from "../../utils/remark/codeBlock";
import { CopyCodeButton } from "./CopyCodeButton";

const langID: { [key: string]: string } = {
  md: "markdown",
  js: "javascript",
  ts: "typescript",
  bash: "shell",
  sh: "shellscript",
  shell: "shell",
  zsh: "shell",
};

const { lang, title: _title, code: _code } = Astro.props as CodeBlockProps;
const code = decodeURIComponent(_code);
const id = `id-${nanoid()}`;
const title = _title ?? langID[lang] ?? lang;
---
<figure>
  <figcaption>
    <span>{title}</span>
  </figcaption>
  <div>
    <Code
    lang={lang as BuiltinLanguage | SpecialLanguage | LanguageRegistration | undefined}
    code={code}
    themes={{ light: "github-light", dark: "github-dark" }}
    />
  </div>
</figure>

import { useCallback, useEffect, useRef, useState } from "react";

export const useCopy = (text: string, duration = 2000) => {
  const [isCopied, setIsCopied] = useState<boolean>(false);
  const timerRef = useRef<NodeJS.Timeout | null>(null);

  const copy = useCallback(async () => {
    try {
      await navigator.clipboard.writeText(text);
      setIsCopied(true);

      // 既存のタイムアウト（前のクリックで設定されたタイムアウト）をクリア
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }

      // 新しいタイムアウトを設定
      timerRef.current = setTimeout(() => {
        setIsCopied(false);
        timerRef.current = null;
      }, duration);
    } catch (error) {
      console.error("[useCopy] Failed to copy text: ", error);
      setIsCopied(false);
    }
  }, [text, duration]);

  // アンマウント時に設定済みのタイムアウトをクリア
  useEffect(() => {
    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, []);

  return { isCopied, copy };
};

import { nanoid } from "nanoid";
import { useCallback, useEffect, useRef, useState } from "react";

export const useRipples = (rippleDuration = 2000) => {
  /*rippleIDのSet: 例: {
      "ripple-id-6TjJ3pn95p_uhSHp6TOyX",
      "ripple-id-nxRg27BibrInBwdRhMVSU",
      "ripple-id--DHaoq_t3jPjGkr44pcI4",
    }
  */
  const [ripples, setRipples] = useState<Set<string>>(new Set());
  /*rippleIDとtimerIDとのMap: 例: {
      "ripple-id-6TjJ3pn95p_uhSHp6TOyX": "1",
      "ripple-id-nxRg27BibrInBwdRhMVSU": "2",
      "ripple-id--DHaoq_t3jPjGkr44pcI4": "3",
    }
  */
 
  const timersRef = useRef<Map<string, NodeJS.Timeout>>(new Map());

  // アンマウント時にタイムアウトをクリア
  useEffect(() => {
    return () => {
      for (const timeoutID of timersRef.current.values()) {
        clearTimeout(timeoutID);
      }
      timersRef.current.clear();
    };
  }, []);

  const addRipple = useCallback(() => {
    const newRippleId = `ripple-id-${nanoid()}`;
    // rippleIDの追加
    setRipples((prevSet) => new Set(prevSet).add(newRippleId));

    const timer = setTimeout(() => {
      // 指定時間後に対応するrippleIDを削除
      setRipples((prevSet) => {
        const newSet = new Set(prevSet);
        newSet.delete(newRippleId);
        return newSet;
      });
      timersRef.current.delete(newRippleId);
    }, rippleDuration);

    timersRef.current.set(newRippleId, timer);

    return newRippleId;
  }, [rippleDuration]);

  return { ripples, addRipple };
};

---
import { Code } from "astro:components";
import { nanoid } from "nanoid";
import type { BuiltinLanguage, LanguageRegistration, SpecialLanguage } from "shiki";
import type { CodeBlockProps } from "../../utils/remark/codeBlock";
import { CopyCodeButton } from "./CopyCodeButton";

// ...

const { lang, title: _title, code: _code } = Astro.props as CodeBlockProps;
const code = decodeURIComponent(_code);
// 空のdivのユニークなID（rippleWrapperId）を生成
const rippleWrapperId = `ripple-wrapper-id-${nanoid()}`;

// ...
---

<figure>
  <figcaption>
    <span data-title={title}>{title}</span>
    <!-- CopyCodeButtonに対象となる空のdivのIDを渡す -->
    <CopyCodeButton code={code} rippleWrapperId={rippleWrapperId} client:visible />
  </figcaption>
  <div>
    <div id={rippleWrapperId} aria-hidden="true"></div>
    <Code
      {/*..*/} 
      code={code}
      themes={{ light: "github-light", dark: "github-dark" }}
    />
  </div>
</figure>

import { useEffect, useRef } from "react";
import { createPortal } from "react-dom";
import { useCopy } from "../../utils/hooks/useCopy";
import { useRipples } from "../../utils/hooks/useRipples";
import styles from "./CopyCodeButton.module.css";

interface CopyCodeButtonProps {
  code: string;
  rippleWrapperId: string;
  text?: string;
}

export const CopyCodeButton = ({
  code,
  rippleWrapperId,
  text = "Code",
}: CopyCodeButtonProps) => {
  const { isCopied, copy } = useCopy(code);
  const { ripples, addRipple } = useRipples();
  const rippleWrapper = useRef<HTMLElement | null>(null);

  // マウント時にReactの管轄外のrippleWrapperをuseRefに保管
  useEffect(() => {
    if (rippleWrapperId) {
      const rippleWrapper = document.getElementById(rippleWrapperId);
      if (rippleWrapper) {
        rippleWrapperRef.current = rippleWrapper;
      }
    }
  }, [rippleWrapperId]);

  const handleClick = async () => {
    await copy(); // コードのコピー
    addRipple(); // rippleの追加
  };

  return (
    <>
      <button
        type="button"
        className={styles["copy-button"]}
        aria-label="copy code button"
        onClick={handleClick}
      >
        <span data-is-copied={isCopied}>Cop</span>
        <span data-is-copied={isCopied}>y</span>
        <span>{text}</span>
      </button>
      // RippleIdのそれぞれについて、rippleの正円を追加（削除するためのタイムアウトが設定されているので、正円が広がるアニメーションの終了に合わせて削除される）
      {Array.from(ripples).map(
        (rippleId) =>
          rippleWrapper.current &&
          createPortal(
            <div aria-hidden="true" key={rippleId} className={styles.ripple} />,
            rippleWrapper.current,
            rippleId,
          ),
      )}
    </>
  );
};

https://slimalized.dev

https://example.com

import ogs from "open-graph-scraper";

const getOpenGraph = async (url: URL) => {
  try {
    const ogResponse = await ogs({ url: url.toString() });
    return ogResponse.result;
  } catch (error) {
    console.error(
      "[getOpenGraph] Failed to get Open Graph: ",
      (error as ErrorResult).result?.error,
    );
    return undefined;
  }
};

/**
 * faviconURLは以下の3パターン：
 * - 絶対パス：e.g. "https://github.githubassets.com/favicons/favicon.svg"
 * - 相対パス：e.g. "/favicon.svg"
 * - undefined
 *
 * 相対パスの場合は絶対パスに変換。undefinedの場合は`https://www.google.com/s2/favicons?domain=${url}`の形に変換する
 */
const resolveFaviconUrl = async (_faviconUrl: string | undefined, url: URL) => {
  const isRelativePath = _faviconUrl && !isValidUrl(_faviconUrl);
  let faviconUrl = isRelativePath
    ? new URL(_faviconUrl, url.origin).toString()
    : _faviconUrl;
  if (faviconUrl === undefined) {
    faviconUrl = `https://www.google.com/s2/favicons?domain=${url}`;

    const response = await fetch(faviconUrl, {
      method: "HEAD",
      signal: AbortSignal.timeout(10000),
    });
    if (!response.ok) {
      return undefined;
    }
  }
  return faviconUrl;
};

const getLinkCardData = async (url: URL) => {
  const ogObject = await getOpenGraph(url);
  if (ogObject === undefined) return;
  return {
    title: ogObject.ogTitle || url.hostname,
    hostname: new URL(url).hostname,
    faviconUrlString: await resolveFaviconUrl(ogObject.favicon, url),
    description: ogObject.ogDescription,
  } satisfies OgData;
};

// ...

export const linkCard: Plugin<[], Root> = () => {
  return async (tree: Root) => {
    // 置換処理の配列
    const transformers: Transformer[] = [];

    // 「非同期処理を必要とする置換処理」を配列に挿入する関数
    const addTransformer = (link: Link, index: number, parent: Parent) => {
      transformers.push(async () => {
        const linkCardData = await getLinkCardData(new URL(link.url));
        if (linkCardData === undefined) return;
        const linkCardNode = createLinkCardNode(link, linkCardData);
        parent.children.splice(index, 1, linkCardNode);
      });
    };

    const visitor: Visitor<Paragraph> = (node, index, parent) => {
      // ...

      const link = node.children[0] as Link;
      const urlString = link.url;
      if (isValidUrl(urlString) && !isTwitterUrl(urlString)) {
        // 1. 非同期処理を必要とする置換処理の関数を、配列に挿入
        addTransformer(link, index, parent);
      }
    };

    visit(tree, "paragraph", visitor);

    // 2. visit終了後、最後にまとめて実行
    const results = await Promise.allSettled(transformers.map((t) => t()));
    for (const [index, result] of results.entries()) {
      if (result.status === "rejected") {
        console.error(
        `[linkCard] Failed to transform link at index ${index}`,
        result.reason,
        );
      }
    }
  };
};

// ...

https://x.com/jack/status/20

interface TweetData {
  // ...
}

interface TweetOEmbedResponse {
  // ...
}

const getTweetData = async (tweet: URL) => {
  // hide_media=true, hide_thread=true を指定して不要な情報を削る
  const oEmbedUrl = new URL(
    `https://publish.twitter.com/oembed?url=${tweet}&hide_media=true&hide_thread=true`,
  );
  // ツイートデータの取得
  const response = await fetch(oEmbedUrl, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
    },
  });
  if (!response.ok) {
    return undefined;
  }
  const result = (await response.json()) as TweetOEmbedResponse;

  // APIから返却されたHTMLをパース・整形する関数（後述）
  const { html, postedDate } = extractTwitterQuote(result.html, result.url);
  if (html === undefined || postedDate === undefined) {
    return undefined;
  }

  return {
    tweetUrlString: result.url,
    authorName: result.author_name,
    authorUrlString: result.author_url,
    html,
    postedDateString: postedDate.toString(),
    referencedDateString: new Date().toString(),
  } satisfies TweetData;
};

<blockquote class="twitter-tweet" ...>
  <p ...>{ツイート本文}</p>
  &mdash; {ユーザー名} (@{ユーザーID})
  <a href="https://twitter.com/.../status/...">
    {投稿日時}
  </a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js" ...></script>

import { JSDOM } from "jsdom";

const extractTwitterQuote = (_html: string, tweetUrlString: string) => {
  // 1. result.htmlをパース（不要なwidget.jsのスクリプトタグの除外も兼ねる）
  const dom = new JSDOM(_html.split("\n")[0]);
  const { document } = dom.window;

  let postedDate: Date | undefined = undefined;
  const aTags = document.getElementsByTagName("a");
  for (const aTag of aTags) {
    // 2. ポスト内に出現するaタグにtarget、rel属性を付与
    aTag.setAttribute("target", "_blank");
    aTag.setAttribute("rel", "noopener noreferrer nofollow");

    const href = aTag.getAttribute("href") || "";
    if (!isValidUrl(href)) continue;

    // 3. 投稿日の取得
    const hrefPath = new URL(href).pathname;
    const tweetPath = new URL(tweetUrlString).pathname;
    if (hrefPath === tweetPath && aTag.textContent) {
      postedDate = new Date(aTag.textContent);
      aTag.parentNode?.removeChild(aTag);
    }
  }
  // 4. ユーザ名表示の削除
  const userNameText = document.getElementsByTagName("p")[0].nextSibling;
  if (userNameText && userNameText.nodeType === dom.window.Node.TEXT_NODE) {
    userNameText.parentNode?.removeChild(userNameText);
  }
  // 5. domを文字列に戻し、blockquoteの内部のみを抽出
  const htmlRegex =
    /^<html><head><\/head><body><blockquote class="twitter-tweet" data-cards="hidden">([\s\S]*?)<\/blockquote><\/body><\/html>$/;
  const html = dom.serialize().match(htmlRegex)?.[1];

  return { html, postedDate };
};

interface FontOptimizingOption {
  fontPath: string; // public/からの相対パスでフォントファイルを指定
  includeTagNames: TagName[]; // 文字抽出対象のタグ名
  excludeTagNames?: TagName[]; // 除外するタグ名
}

const fontOptimizingOptions: FontOptimizingOption[] = [
  {
    // 1. Noto Sans JP 400: 基本文字用
    fontPath: "fonts/noto-sans-jp_regular_400.woff2",
    includeTagNames: ["body"],
    excludeTagNames: ["script", "strong"],
  },
  {
    // 2. Noto Sans JP 700: <strong>用
    fontPath: "fonts/noto-sans-jp_bold_700.woff2",
    includeTagNames: ["strong"],
  },
];

// 与えられたhtmlファイルを読み込み、使用文字を抽出する関数
const collectTextContentFromHTML = async (
  htmlFilePath: string,
  fontOptimizingOption: FontOptimizingOption,
): Promise<string> => {
  const { includeTagNames, excludeTagNames } = fontOptimizingOption;
  const textContents: string[] = [];

  try {
    // HTMLファイルを読み込む
    const htmlContent = await fs.readFile(htmlFilePath, "utf-8");
    const virtualConsole = new VirtualConsole();
    virtualConsole.on("error", () => {}); // JSDOMのエラーは無視
    const { document } = new JSDOM(htmlContent, { virtualConsole }).window;

    // 1. 除外タグをDOMから削除
    const ExcludeDoms = (excludeTagNames ?? []).flatMap((tagName) =>
      Array.from(document.getElementsByTagName(tagName)),
    );
    for (const dom of ExcludeDoms) {
      dom.remove();
    }

    // 2. 指定タグからテキストを抽出
    const IncludeDoms = includeTagNames.flatMap((tagName) =>
      Array.from(document.getElementsByTagName(tagName)),
    );
    for (const dom of IncludeDoms) {
      // 改行を除去し、前後の空白をトリム
      const textContent = dom.textContent?.replace(/\n/g, "").trim() ?? "";
      textContents.push(textContent);
    }
  } catch (error) {
    console.error(
      `[collectTextContentFromHTML] HTMLファイルの処理に失敗しました: ${htmlFilePath}`,
      error,
    );
  }

  return textContents.join("");
};

// 各HTMLファイルに`collectTextContentFromHTML`を適用し、使用文字を抽出する関数
const extractUsedCharacters = async (
  htmlFilePaths: string[],
  fontOptimizingOption: FontOptimizingOption,
): Promise<string> => {
  const textContents: string[] = [];
  for (const htmlFilePath of htmlFilePaths) {
    // 各HTMLファイルからテキストを抽出
    const textContent = await collectTextContentFromHTML(
      htmlFilePath,
      fontOptimizingOption,
    );
    textContents.push(textContent);
  }
  // すべての文字から重複を除去
  const characterSet = new Set(textContents.join(""));
  const usedCharacters = Array.from(characterSet).join("");
  return usedCharacters;
};

const optimizeFonts = async (
  htmlFilePaths: string[],
  fontOptimizingOption: FontOptimizingOption,
  dir: URL,
): Promise<FontOptimizingLogInfo | undefined> => {
  const { fontPath } = fontOptimizingOption;

  // 1. HTMLファイルから使用文字を抽出する
  const usedCharacters = await extractUsedCharacters(
    htmlFilePaths,
    fontOptimizingOption,
  );

  // 2. フォントファイルのパスを生成する
  let fontFilePath: string;
  if (URL.canParse(fontPath, dir)) {
    fontFilePath = new URL(fontPath, dir).pathname;
  } else {
    console.error(`[optimizeFonts] Invalid font file path: ${fontPath}`);
    return;
  }

  const prevFileSize = (await fs.stat(fontFilePath)).size;

  // 3. フォントファイルを読み込む
  let rawFontData: Buffer;
  try {
    rawFontData = await fs.readFile(fontFilePath);
  } catch (error) {
    console.error(
      `[optimizeFonts] Failed to read font file: ${fontFilePath}`,
      error,
    );
    return;
  }

  // 4. フォントをサブセット化
  let optimizedFontData: Buffer;
  try {
    optimizedFontData = await subsetFont(rawFontData, usedCharacters, {
      targetFormat: "woff2",
    });
  } catch (error) {
    console.error(`[optimizeFonts] Failed to subset font: ${fontPath}`, error);
    return;
  }

  // 5. サブセット化したフォントを書き込む
  try {
    await fs.writeFile(fontFilePath, optimizedFontData);
  } catch (error) {
    console.error(
      `[optimizeFonts] Failed to write optimized font file: ${fontFilePath}`,
      error,
    );
    return;
  }

  // ログ用の情報を返す
  const optimizedFileSize = (await fs.stat(fontFilePath)).size;
  const charsLength = usedCharacters.length;

  return {
    fontPath,
    prevFileSize,
    optimizedFileSize,
    charsLength,
  };
};

// 1. インテグレーションの作成
export const customIntegration = (): AstroIntegration => ({
  name: "custom-integration", // ログ出力時に使われる名前
  hooks: {
    // "フック名": コールバック関数
    "astro:build:done": async (options: {
      // ... 任意でオプションを付与
    }) => {
      // 処理の記述
    },
  },
});

// 2. インテグレーションを使用
// astro.config.mjs
import { customIntegration } from "..."

export default defineConfig({
  integrations: [customIntegration()],
});

// ...
export const fontOptimizer = (): AstroIntegration => ({
  name: "font-optimizer",
  hooks: {
    "astro:build:done": async (options: {
      dir: URL;
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => {
      const urls: URL[] = Array.from(options.assets.values()).flat();
      const htmlFilePaths = urls
        .map((url) => url.pathname)
        .filter((pathname) => pathname.endsWith("html"));

      if (htmlFilePaths.length === 0) {
        options.logger.info("No html files. Font optimizer skipped.");
        return;
      }

      console.log(kleur.bgGreen().black(" optimizing fonts ")); // ログ開始

      for (const fontOptimizingOption of fontOptimizingOptions) {
        const logInfo = await optimizeFonts(
          htmlFilePaths,
          fontOptimizingOption,
          options.dir,
        );
        if (logInfo) {
          const logMessage = [
            kleur.gray("Optimized"),
            logInfo.fontPath,
            kleur.gray(
              `(${kleur.yellow(fileKBSize(logInfo.prevFileSize))} kB ->`,
            ),
            kleur.green(fileKBSize(logInfo.optimizedFileSize)),
            kleur.gray(`kB | ${logInfo.charsLength} chars)`),
          ].join(" ");
          options.logger.info(logMessage);
        }
      }

      console.log(" "); // ログの空行
    },
  },
});

:root[data-theme="light"] {
  color-scheme: light; /* ブラウザのUI（スクロールバー等）をライトに */

  /* ...（ライトモード用のカラー変数を定義） */
}

:root[data-theme="dark"] {
  color-scheme: dark; /* ブラウザのUI（スクロールバー等）をダークに */

  /* ...（ダークモード用のカラー変数を定義） */
}

import { useSyncExternalStore } from "react";

const themes = {
  dark: true,
  light: true,
  undefined: true,
} as const satisfies Record<string, true>;

type Theme = keyof typeof themes;

const isTheme = (value: string): value is Theme => {
  return value in themes;
};

const EVENT_THEME_STORAGE_CHANGE = "themeStorageChange";
const THEME_KEY = "site-theme";

const subscribe = (onChange: () => void) => {
  window.addEventListener(EVENT_THEME_STORAGE_CHANGE, onChange);
  return () => window.removeEventListener(EVENT_THEME_STORAGE_CHANGE, onChange);
};

export const useTheme = (initialTheme: Theme = "undefined") => {
  const setTheme = (theme: Theme) => {
    window.localStorage.setItem(THEME_KEY, theme);
    window.dispatchEvent(new Event(EVENT_THEME_STORAGE_CHANGE));
  };

  const toggleTheme = (theme: Theme) => {
    if (theme === "undefined") return;
    const toggledTheme: Theme = theme === "dark" ? "light" : "dark";
    setTheme(toggledTheme);
  };

  const getTheme = () => {
    try {
      const theme = window.localStorage.getItem(THEME_KEY);
      if (theme && isTheme(theme)) {
        return theme;
      }
    } catch (error) {
      console.error(
        "[useTheme] Failed to get theme from local storage: ",
        error,
      );
    }
  };

  const theme = useSyncExternalStore(
    subscribe,
    () => getTheme() ?? initialTheme,
    () => initialTheme,
  );

  return { theme, setTheme, toggleTheme };
};

const subscribe = (onChange: () => void) => {
    window.addEventListener(EVENT_THEME_STORAGE_CHANGE, onChange);
  return () => window.removeEventListener(EVENT_THEME_STORAGE_CHANGE, onChange);
};

// ...

const setTheme = (theme: Theme) => {
    window.localStorage.setItem(THEME_KEY, theme);
    window.dispatchEvent(new Event(EVENT_THEME_STORAGE_CHANGE));
};

// ...

const theme = useSyncExternalStore(
    subscribe,
    () => getTheme() ?? initialTheme,
    () => initialTheme, // "undefined"
);

import { useEffect } from "react";
import { useTheme } from "../utils/hooks/useTheme";
import styles from "./ToggleThemeButton.module.css";

export const ToggleThemeButton = () => {
  const { theme, toggleTheme } = useTheme();

  useEffect(() => {
    if (theme !== "undefined") {
      window.document.documentElement.setAttribute("data-theme", theme);
    }

    return () => {
      if (theme !== "undefined") {
        window.document.documentElement.removeAttribute("data-theme");
      }
    };
  }, [theme]);

  return (
    <button
      type="button"
      id={styles["toggle-theme-button"]}
      aria-label={
        theme === "dark" ? "Switch to light theme" : "Switch to dark theme"
      }
      data-theme={theme}
      onClick={() => toggleTheme(theme)}
    >
      {theme !== "undefined" && (
        <>
          <span>to Dark</span>
          <span>to Light</span>
        </>
      )}
    </button>
  );
};

{/* ... */}

  <head>
    {/* ... */}
    <script is:inline>
      {/* is:inlineディレクティブをつけると、ビルド時にAstroが処理をスキップしてくれるので、そのままHTMLにscriptをレンダリングできる */}
      (function () {
        // 1. まずlocalStorageからテーマを取得
        const theme = localStorage.getItem("site-theme");
        if (theme === "dark" || theme === "light") {
          document.documentElement.setAttribute("data-theme", theme);
        } else {
          // 2. localStorageにない場合、OSの設定（prefers-color-scheme）を優先
          const preferTheme = window.matchMedia("(prefers-color-scheme: dark)")
            ? "dark"
            : "light";
          localStorage.setItem("site-theme", preferTheme);
          document.documentElement.setAttribute("data-theme", preferTheme);
        }
      })();
    </script>
    {/* ... */}
  </head>

{/* ...  */}

---
const { heading } = await render(entry);
---

// 深さ2, 3, 4 の見出しのみ使用
const depth = [2, 3, 4] as const;
type Depth = (typeof depth)[number];

const isValidDepth = (number: number): number is Depth => {
  return depth.some((d) => d === number);
};

const CreateTableOfContentsList = (
  headings: MarkdownHeading[],
  baseDepth: Depth,
  activeIds: Set<string>,
  itemRefs: RefObject<Record<string, HTMLAnchorElement | null>>,
) => {
  const toc: JSX.Element[] = [];
  for (const [index, heading] of headings.entries()) {
    const { depth: currentDepth, slug, text } = heading;

    if (!isValidDepth(currentDepth)) {
      console.error("[TableOfContents] Invalid heading depth:", currentDepth);
      continue;
    }

    // 基準の深さよりも浅い見出しに衝突したら、見出し作成を中断
    if (currentDepth < baseDepth) break;

    // 基準の深さと同じ深さの見出しに衝突したら、要素を作成
    if (currentDepth === baseDepth) {
      const nextIndex = index + 1;
      const nextDepth: number | undefined = headings[nextIndex]?.depth;
      toc.push(
        <li key={slug}>
          <a
            href={`#${slug}`}
            ref={(AnchorElement) => {
              itemRefs.current[slug] = AnchorElement;
            }}
            data-is-active={activeIds?.has(slug) ? "true" : undefined}
          >
            {text}
          </a>
          // 次の見出しが基準の深さよりも深ければ、その深さを基準に再帰的に関数を呼び出す
          {isValidDepth(nextDepth) &&
            nextDepth > baseDepth &&
            CreateTableOfContentsList(
              headings.slice(nextIndex),
              nextDepth,
              activeIds,
              itemRefs,
            )}
        </li>,
      );
    }

    // 基準の深さよりも深い見出しに衝突したら、何も行わない（continue）
  }

  return toc.length > 0 ? (
    <ol className={styles[`ol-depth-${baseDepth}`]}>{[...toc]}</ol>
  ) : null;
};

// ... (observerOptionsの設定)
// ...
  useEffect(() => {
    // ... (見出し要素のDOMを取得)
    
    const observer = new IntersectionObserver((entries) => {
      setActiveIds((prev) => {
        const next: Set<string> = new Set(/* ... */);

        // entry.isIntersectingで画面内に見出しがあるかを判定し、強調するべき見出し要素を抽出する
        for (const entry of entries) {
          const id = entry.target.id;
          if (!id) continue;
          if (entry.isIntersecting) {
            next.add(id);
          } else {
            next.delete(id);
          }
        }

        // ビューポートに1つも見出し要素が無ければ、現在の項目の見出しのみを強調する
        if (
          next.size === 0 &&
          entries.length === 1 &&
          !entries[0].isIntersecting
        ) {
          scrollDirectionRef.current =
            entries[0].boundingClientRect.y < 0 ? "down" : "up";
          if (scrollDirectionRef.current === "down") {
            return new Set([entries[0].target.id]);
          }
          if (scrollDirectionRef.current === "up") {
            // ... (一つ前の見出しIDを取得してセット)
        }

        // Stateの更新
        if (prev.size !== next.size || [...prev].some((id) => !next.has(id))) {
          return next;
        }
        return prev;
      });
    }, observerOptions);

    // 見出しを監視対象として登録
    for (const headingElement of headingElementsRef.current) {
      observer.observe(headingElement);
    }

    return () => observer.disconnect();
  }, []);
// ...

bun mediaConverter.ts {posts|works}/{id} [--delete-original]

const validExts = [".png", ".jpg", ".jpeg", ".webp"];

// 対象の拡張子であるかを返す関数
export const isValidImageSource = (fileName: string) => {
  const lower = fileName.toLowerCase();
  const isAVIF = lower.endsWith(".avif");
  const isSVG = lower.endsWith(".svg");
  const isImage =
    isAVIF || isSVG || validExts.some((ext) => lower.endsWith(ext));
  return { isImage, isAVIF, isSVG };
};
// ...
  const dirPath = path.resolve(__dirname, "../../../media", dirName);

  let imageEntries: Dirent[];
  // ...
    // 対象のファイルのみに絞り込み
    imageEntries = (await fs.readdir(dirPath, { withFileTypes: true })).filter(
      (entry) => {
        if (!entry.isFile()) return false;
        const { isImage, isAVIF, isSVG } = isValidImageSource(entry.name);
        return isImage && !isAVIF && !isSVG;
      },
    );
  // ...

export const imageSizes = {
  small: 400, 
  large: 720, 
  original: 0, // オリジナルサイズ（リサイズなしを示すため0を指定）
} as const;
type SizeLabel = keyof typeof imageSizes;
// ...
// filePathの画像からsizeLabelに指定したサイズの`.avif`に変換した画像を生成する
const convertToAvif = async (filePath: string, sizeLabel: SizeLabel) => {
  const { base, name } = path.parse(filePath);

  const boundaryWidth = imageSizes[sizeLabel];
  // 1. 元の横幅を取得
  let originalWidth: number | undefined;
  try {
    originalWidth = (await sharp(filePath).metadata()).width;
  } catch (error) {
    throw new Error(`Failed to get metadata for ${base}: ${error}`);
  }
  if (!originalWidth) {
    throw new Error(`Failed to get width for ${base}`);
  }

  // 2. 元の横幅が指定のサイズよりも小さければ、画像の生成をスキップ
  if (originalWidth <= boundaryWidth) {
    // ...
    return;
  }

  let avifBuffer: Buffer;
  try {
    // 3. .avif画像の生成
    const sharpInstance = sharp(filePath);
    if (sizeLabel !== "original") {
      sharpInstance.resize({ width: boundaryWidth });
    }
    avifBuffer = await sharpInstance.avif({ quality: 80 }).toBuffer();
  } catch (error) {
    throw new Error(`Failed to convert ${base} to AVIF: ${error}`);
  }

  // 4. ファイルを書き込み
  const outputFileName =
    sizeLabel !== "original" ? `${name}_${sizeLabel}.avif` : `${name}.avif`;
  const outputFilePath = path.join(path.dirname(filePath), outputFileName);
  try {
    await fs.writeFile(outputFilePath, avifBuffer);
     // ...
  } catch (error) {
    throw new Error(`Failed to write ${outputFileName}: ${error}`);
  }
};

import {
 ListObjectsV2Command,
 PutObjectCommand,
 S3Client,
} from "@aws-sdk/client-s3";

// .env から認証に必要なシークレット情報を読み込み
const ACCOUNT_ID = process.env.ACCOUNT_ID;
const ACCESS_KEY_ID = process.env.ACCESS_KEY_ID;
const SECRET_ACCESS_KEY = process.env.SECRET_ACCESS_KEY;
const BUCKET_NAME = process.env.BUCKET_NAME;

// R2のエンドポイントを指定してS3クライアントを生成
const r2Client = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: ACCESS_KEY_ID,
    secretAccessKey: SECRET_ACCESS_KEY,
  },
});

// リソースオブジェクトのアップロード
const uploadParams = {
  Bucket: BUCKET_NAME,
  Key: "posts/sample/hello.avif" // 参照時の名前になる。`/`を含めて階層化可能
  // この場合、`https://${ACCOUNT_ID}.r2.cloudflarestorage.com/posts/sample/hello.avif`になる
  Body: await fs.readFile("../media/posts/sample/hello.avif"), // アップロードするファイル
  ContentType: "image/avif",
};
await r2Client.send(new PutObjectCommand(uploadParams));

// リソースオブジェクトの取得
const { Contents } = await r2Client.send(
  new ListObjectsV2Command({
    Bucket: BUCKET_NAME,
    Prefix: `posts/`, // 特定のプレフィクスを持つオブジェクトを取得
  }),
);

bun r2Uploader.ts {posts|works}/{id} [--update-all]

bun imageSrcReplacer.ts {posts|works}/{mdx file name} 

---
import sharp from "sharp";
import { imageSizes } from "../../utils/scripts/mediaConverter";

interface Props { /*...*/ }
const { alt, src: _src, loading = "lazy" } = Astro.props;

// 元のURLからsmall版、large版のURLを生成
const extRegex = /\.(avif|svg)$/;
const src = {
  original: _src, // 例：https://media.slimalized.dev/posts/sample/hello.avif
  small: _src.replace(extRegex, "_small.$1"), // 例：https://media.slimalized.dev/posts/sample/hello_small.avif
  large: _src.replace(extRegex, "_large.$1"), // 例：https://media.slimalized.dev/posts/sample/hello_large.avif
};

const res = await fetch(src.original);
const buffer = Buffer.from(await res.arrayBuffer());
const metadata = await sharp(buffer).metadata();
// オリジナル画像のサイズを取得し、small版、large版の画像widthを決定（「オリジナルのwidth」と「既定値（small: 400px, large: 720px）」のうち小さい方の数値）
const { width: originalWidth, height: originalHeight } = metadata;
const isValid = originalWidth !== undefined && originalHeight !== undefined;
const smallWidth = isValid ? Math.min(imageSizes.small, originalWidth) : undefined;
const largeWidth = isValid ? Math.min(imageSizes.large, originalWidth) : undefined;
---
<!-- ... -->
  <picture>
    {/* 画面の横幅が400px以下の場合はsmallサイズの画像を読み込む */}
    <source
      media={`(max-width: ${imageSizes.small}px)`}
      srcset={imageSizes.small >= originalWidth ? src.original : src.small}
      width={smallWidth}
      height={Math.floor(((smallWidth as number) * originalHeight) / originalWidth)}
    />
    {/* 画面の横幅が400pxより大きい場合はlargeサイズの画像を読み込む */}
    <img
      src={imageSizes.large >= originalWidth ? src.original : src.large}
      alt={alt}
      width={largeWidth}
      {/* オリジナル画像の縦横幅の比率から、画像の高さを指定 */}
      height={Math.floor(((largeWidth as number) * originalHeight) / originalWidth)}
      loading={loading}
    />
  </picture>
<!-- ... -->

https://slimalized.dev/posts/build-astro-site/og-image.png

import { getCollection } from "astro:content";
import type { APIRoute } from "astro";
import { generateOgpImage } from "../../../components/OgpImage";
import { formatDate } from "../../../utils/formatDate";

export const getStaticPaths = async () => {
  const posts = await getCollection("posts");
    return posts.map((post) => ({
    params: {
      id: post.id,
    },
    props: {
      title: post.data.title,
      date: post.data.publishedDate,
    },
  }));
};

export const GET: APIRoute = async ({ params, props }) => {
  if (!params.id) {
    return new Response(
      JSON.stringify({
        error: "Post ID is required.",
      }),
    { status: 400 },
    );
  }
  const body = await generateOgpImage(props.title, formatDate(props.date));

  return new Response(body, {
    headers: {
      "Content-Type": "image/png",
    },
    status: 200,
  });
};

import fs from "node:fs/promises";
import path from "node:path";
import satori from "satori";
import sharp from "sharp";

const getFont = async (
  fontFilePath = "src/assets/zen-kaku-gothic-new_medium_500.ttf",
) => {
  try {
    return await fs.readFile(path.resolve(process.cwd(), fontFilePath));
  } catch (error) {
    console.error("Error reading font file:", error);
    throw new Error("Failed to load font.");
  }
};

export const generateOgpImage = async (title: string, date: string) => {
  const bgPath = path.resolve(process.cwd(), "src/assets/og-image-bg.png");
  const bgBuffer = await fs.readFile(bgPath);
  const bgSrc = `data:image/png;base64,${bgBuffer.toString("base64")}`;

  // ...
  const svg = await satori(
    <div>
      {/*背景画像*/}
      <img src={bgSrc} width={1200} height={630} {/*...*/} />
      {/* タイトルや公開日などの要素を記述 */}
    </div>,
    {
      width: 1200,
      height: 630,
      fonts: [
        {
          name: "Zen Kaku Gothic New",
          data: await getFont(),
          style: "normal",
          weight: 500,
        },
      ],
    },
  );

  return await sharp(Buffer.from(svg)).png().toBuffer();
};

<meta property="og:image" content={new URL("/posts/hello/sample/og-image.png", Astro.url)} />