このサイトを構成している技術の全体像

1. まず全体像を見る

このサイトの技術は、「書く」「組み立てる」「探す」「図解する」「公開する」の5つに分けると理解しやすいです。

flowchart LR
  W["記事を書く\nMarkdown / MDX"] --> C["記事を管理する\nAstro Content Collections"]
  C --> A["ページを生成する\nAstro"]
  A --> H["静的HTML/CSS/JS\n dist/"]
  H --> P["検索インデックスを作る\nPagefind"]
  H --> D["公開する\nCloudflare Pages"]
  G["変更履歴を残す\nGit / GitHub"] --> D
  M["図解を書く\nMermaid"] --> W

2. Astroはサイトを組み立てる道具

Astroは、Markdown中心のコンテンツサイトを作りやすい静的サイトジェネレーターです。

このサイトでは、src/pages/ に置いたAstroファイルがURLになります。たとえばトップページは src/pages/index.astro、記事一覧は src/pages/articles/index.astro、記事ページは src/pages/articles/[...slug].astro が担当します。

設定ファイルでは、現在このように静的サイトとして出力する指定になっています。

import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";

export default defineConfig({
  site: "https://my-tech.pages.dev",
  output: "static",
  integrations: [mdx()]
});

3. MarkdownとMDXは記事を書くための形式

記事本文は、基本的にMarkdownまたはMDXで書きます。文章を主役にできるので、技術ノートを増やしやすい形式です。

Markdownは、見出し、段落、リスト、表、コードブロックなどを軽い記法で書ける形式です。MDXはMarkdownに加えて、AstroコンポーネントやJSXに近い表現を使える形式です。

記事の先頭にはfrontmatterを書きます。これは記事のタイトル、説明、カテゴリ、タグ、更新日などをページ側で使うためのメタ情報です。

---
title: "記事タイトル"
description: "記事の説明"
category: "開発ツール"
categorySlug: "tools"
tags: ["Astro", "Markdown"]
level: "beginner"
updated: "2026-05-19"
draft: false
---

4. Content Collectionsは記事の形をそろえる仕組み

Content Collectionsは、記事ファイルの集まりをAstroから安全に扱うための仕組みです。

このサイトでは、記事は src/content/articles/ 以下に置きます。カテゴリごとに web/、languages/、tools/ のようなフォルダに分かれています。

flowchart TD
  Root["src/content/articles/"] --> Web["web/"]
  Root --> Lang["languages/"]
  Root --> Tools["tools/"]
  Web --> A1["web-technology-complete-guide.md"]
  Lang --> A2["python-uv-complete-guide.md"]
  Tools --> A3["site-technology-stack-guide.md"]
  Config["src/content.config.ts"] --> Root

src/content.config.ts では、記事に必要なfrontmatterの形が定義されています。

const articles = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string(),
    category: z.string(),
    categorySlug: z.string(),
    tags: z.array(z.string()),
    level: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),
    updated: z.string(),
    draft: z.boolean().default(false)
  })
});

これにより、記事に title や categorySlug が足りない場合、ビルド時に気づきやすくなります。記事が増えても、一覧ページやカテゴリページが同じ形のデータとして扱えるのが利点です。

5. Pagefindは静的サイトに検索を足す道具

Pagefindは、完成したHTMLを読み取り、ブラウザ上で使える検索インデックスを作るツールです。

このサイトの package.json には、検索用のコマンドが用意されています。

{
  "scripts": {
    "build": "astro build",
    "pagefind": "pagefind --site dist",
    "build:search": "astro build && pagefind --site dist"
  }
}

6. Mermaidは図解をテキストで書く道具

Mermaidを使うと、フローチャートや関係図をテキストとして記事内に保存できます。

このサイトの記事では、次のように pre と mermaid クラスを使って図を置いています。

<div class="diagram">
<pre class="mermaid">
flowchart LR
  A["記事を書く"] --> B["ビルドする"]
  B --> C["公開する"]
</pre>
</div>

画像ファイルとして図を作る方法と違い、本文と同じGit管理に載せられます。あとから文章を直すのと同じ感覚で図も直せるため、技術解説記事と相性がよいです。

7. Cloudflare Pagesは静的ファイルを公開する場所

Cloudflare Pagesは、ビルド済みの静的ファイルをインターネットに配信するホスティングサービスです。

このサイトは output: "static" のAstroサイトなので、基本的には次の流れで公開できます。

1. 記事やコードを編集する
2. npm run build で dist/ を生成する
3. GitHubへ変更を反映する
4. Cloudflare Pagesがビルドして公開する

Cloudflare Pages側の代表的な設定は、Astroの公式手順では次のようになります。

8. 記事を追加するときの作業順

このサイトで新しい記事を追加するときは、ファイル作成、frontmatter記入、本文作成、ビルド確認の順に進めます。

# 依存関係を入れていない場合だけ実行
npm install

# 開発サーバーを起動
npm run dev

# 公開用HTMLを生成して確認
npm run build

# 検索インデックスまで作る
npm run build:search

9. よくあるつまずき

静的サイトは仕組みが軽い一方で、記事ファイルの書き方やビルド順を間違えると表示に影響します。

10. まず覚えること

このサイトは、文章を増やしやすく、静的に速く配信できる構成です。

• Astroは、記事やページを静的HTMLへ組み立てる。
• Markdown/MDXは、記事本文を書くための形式。
• Content Collectionsは、記事のメタ情報をそろえて扱う仕組み。
• Pagefindは、ビルド済みHTMLから検索を作る。
• Mermaidは、図解をテキストで管理する。
• Cloudflare Pagesは、生成された dist/ を公開する場所。
• GitHubは、変更履歴とデプロイ連携の中心になる。

参考ソース

• Astro Docs: Content Collections
• Astro Docs: @astrojs/mdx
• Pagefind 公式サイト
• Pagefind Docs: Running Pagefind
• Astro Docs: Deploy your Astro Site to Cloudflare Pages
• Mermaid Docs: About Mermaid