Markdown / MDX 執筆ガイド

本記事では、Markdown の基本的な記法、Astro Plain に統合された Expressive Code、GitHub スタイルの警告ブロック、および Starlight 由来の MDX コンポーネントの使い方を紹介します。

読了時間: 13分
著者：
ルカ
サンプル
AstroMDXMarkdownExpressive Codeガイド

NOTE

本記事はAIを用いて翻訳されています。

Markdown の基本記法

見出し

Markdown では # から ###### を使って見出しレベル 1〜6 を表現します：

見出し 1 (H1)

見出し 2 (H2)

見出し 3 (H3)

見出し 4 (H4)

見出し 5 (H5)
見出し 6 (H6)

テキストの書式

プレビューMarkdown
太字テキスト**太字テキスト** または __太字テキスト__
斜体テキスト*斜体テキスト* または _斜体テキスト_
太字と斜体***太字と斜体***
打ち消し線~~打ち消し線~~
インラインコード`インラインコード`
Ctrl + C<kbd>Ctrl</kbd> + <kbd>C</kbd>

引用とネスト引用

これは基本的な引用文です。

これはネストされた第2レベルの引用文です。

引用内でも 太字 や インラインコード が使えます。

リストとタスクリスト

箇条書きリスト：

  • 項目 1
    • サブ項目 A
    • サブ項目 B
  • 項目 2

番号付きリスト：

  1. フェーズ 1：環境構築
  2. フェーズ 2：開発とビルド
  3. フェーズ 3：デプロイと公開

タスクリスト (Task Lists)：

  • コア機能の設計が完了
  • 静的多言語ルーティングと i18n
  • ドキュメントの補充と改善が進行中

テーブルと配置

左揃えヘッダー中央揃えヘッダー右揃えヘッダー
AstroSSG / SSR高速読み込み
Expressive Codeシンタックスハイライトマルチテーマ対応
Pagefind全文検索静的サイト対応

リンクと画像

TIP

MDX ドキュメントで Astro の Image や Picture コンポーネントを使うと、自動リサイズ、フォーマット変換、遅延読み込みなど、Astro の画像最適化機能を活用できます。

カバー画像

GitHub スタイルの警告ブロック (BlockquoteAlerts)

remark-github-blockquote-alert （新しいタブで開く） をベースに、 > [!TYPE] 構文でさまざまな種類の警告ブロックを作成できます：

NOTE

一般的な背景・文脈・補足知識を記録するために使います。

TIP

開発効率や使い勝手を向上させるヒントを提供します。

IMPORTANT

ユーザーが必ず知っておくべき、見逃せない重要情報を強調します。

WARNING

ビルドの失敗や予期せぬ動作を引き起こす可能性のある注意点を示します。

CAUTION

データ損失やセキュリティリスクにつながる重大な危険を警告します。

脚注 (Footnotes)

これは脚注付きの文章です1。

脚注は複数行にわたることもできます2。

コードハイライト

本プロジェクトでは Expressive Code （新しいタブで開く） をコードハイライトに使用しています。

コードブロックのタイトル

コードブロックのメタ情報に title="..." を追加すると、ブロック上部にタイトルが表示されます：

src/utils/math.ts
export function calculateSum(a: number, b: number): number {
  return a + b;
}

行番号と行のハイライト

showLineNumbers で行番号を有効にし、{行番号の範囲} で特定の行をハイライトします：

src/services/api.ts
export async function fetchData(endpoint: string) {
  const url = `https://api.example.com/${endpoint}`;
  try {
    const response = await fetch(url);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Fetch failed:", error);
    throw error;
  }
}

差分と追加・削除マーカー

ins={...} と del={...} で追加または削除された行をマークします：

package.json
{
  "name": "my-astro-blog",
  "version": "1.0.0",
  "version": "2.0.0"
}

または diff コードブロックを使う方法もあります：

git diff site.config.ts
export default {
  allowRobots: false,
  allowRobots: true,
  postsPerPage: 10,
};

テキストハイライト

ins="テキスト"、del="テキスト"、または "キーワード" でコードブロック内の特定テキストをハイライトします：

app.js
const express = require("express");
const app = express();
const port = 3000;


app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

コードの折り畳み

長いコードには collapse={開始行-終了行} を使って、指定した行をデフォルトで折り畳みます：

long-script.ts
import { defineCollection, z } from "astro:content";
7 collapsed lines


// 多くのフィールド定義を含むスキーマ
const baseSchema = z.object({
  id: z.string(),
  createdTime: z.date(),
  updatedTime: z.date(),
  status: z.enum(["draft", "published", "archived"]),
});


export const collections = {
  posts: defineCollection({ schema: baseSchema }),
};

ターミナルスタイル

frame="terminal" を使うと、コードブロックをタイトルバーと操作ボタン付きのターミナルウィンドウとして表示できます：

インストールと起動
# テンプレートリポジトリをクローン
git clone https://github.com/Aaakul/astro-plain.git my-blog


# ディレクトリに移動して依存関係をインストール
cd my-blog
pnpm install


# ローカル開発サーバーを起動
pnpm dev

組み込み MDX コンポーネント

.mdx ファイルでは、以下のコンポーネントがグローバルに登録されており、手動でインポートせずに使用できます。

Steps コンポーネント

<Steps> はステップごとの操作手順を記述するためのもので、各ステップに自動的に番号が付与されます。ネストした段落・コードブロック・タブをサポートしています。

基本的な使い方

  1. ステップ 1：リポジトリをローカルマシンにクローンします。
  2. ステップ 2：プロジェクトのルートディレクトリで依存関係をインストールします。
  3. ステップ 3：dev コマンドを実行してライブプレビューを開始します。

組み合わせた使い方

  1. 設定ファイルを編集する

    site.config.ts を編集します：

    site.config.ts
    export default {
      siteUrl: "https://example.com",
      defaultLanguage: "ja-JP",
    };

  2. 依存関係をインストールする

    好みのパッケージマネージャーを選んでください：

    Terminal window
    bun install

  3. 開発サーバーを起動する

    起動後、ターミナルにアクセス先の URL またはポート番号が表示されます。ブラウザで開くとプレビューできます。

FileTree コンポーネント

<FileTree> は階層インデントとファイルタイプアイコン付きのディレクトリツリーを生成します。

機能：

  • ディレクトリの識別：名前の末尾にスラッシュ / を付ける（例：src/）とディレクトリを表します。
  • 特定のファイル/ディレクトリを強調：太字構文 **ファイル名** を使います。
  • 行末の説明：ファイル名の後にスペースと説明テキストを追加します。
  • 省略記号のプレースホルダー：... を使って省略されたファイルを表します。
  • ディレクトリi18n/
    • …
    • ディレクトリmessages/ 各言語の翻訳辞書
      • zh-Hans.ts 中国語辞書
      • en-US.ts 英語辞書
      • ja-JP.ts 日本語辞書
  • ディレクトリsrc/content/
    • ディレクトリblog/ ブログ記事（translationKey で紐付け）
      • …
    • ディレクトリauthor/ 著者情報（言語別フォルダで管理）
      • …
    • ディレクトリproject/ プロジェクト紹介（言語別フォルダで管理）
      • …
    • ディレクトリmdx/ その他の MDX コンテンツ（言語別フォルダで管理）
      • ディレクトリ[lang]/
        • hero.mdx ヒーローセクション
  • site.config.ts サイトのコア設定ファイル
  • …

Tabs コンポーネント

<Tabs> と <TabItem> は、同じコンテンツの異なるバージョンや関連オプションをタブにまとめて整理します。

アイコンとコンポーネント間の同期 (syncKey)

同じ syncKey を持つ <Tabs> は選択状態を共有します。一方のタブを切り替えると、同じ syncKey を持つ他のタブも同期して更新されます。

Terminal window
  bun --bun run dev
Terminal window
bun install
 
<Tabs syncKey="pkg-manager">
  <TabItem label="Bun" icon="bun">
    ```bash
      bun --bun run dev
    ```


  </TabItem>
15 collapsed lines


  <TabItem label="pnpm" icon="pnpm">
    ```bash
    pnpm run dev
    ```


  </TabItem>


  <TabItem label="npm" icon="npm">
    ```bash
    npm run dev
    ```


  </TabItem>
</Tabs>

Footnotes

  1. これは1行の脚注の内容です。 ↩

  2. これは複数行の脚注の1行目です。 これは複数行の脚注の2行目です。 ↩

最終更新日：

関連記事

最終更新日：

Astro Plain 使用ガイド

サンプル
Astroフロントエンドブログテンプレートガイド

Astro Plain は Astro ベースのミニマルな多言語静的ブログテンプレートで、CSS / UI フレームワークに依存しません。この記事では、Astro Plain の機能紹介、設定説明、コンテンツ管理やデプロイ手順が含まれています。

最終更新日：

国際化ガイド

サンプル
Astroi18n国際化ガイド

Astro Plain の国際化（i18n）ガイド：翻訳関数の使い方と新しい言語の追加手順。