MDX記述サンプル集 - MDX Writing Samples

このページでは、MDXで記事を書く際に使用できる機能とサンプルコードを紹介します。記事執筆者が参考にできる包括的なガイドです。

ページの基本構造 - Basic Page Structure

MDXページは必ずメタデータとメインタイトルから始めます:

export const metadata = {
title: 'ページタイトル',
description: 'ページの説明文です。',
}

# メインタイトル

見出しの使い方 - Heading Usage

見出しは記事の構造を作る重要な要素です。H1は1ページに1つまで、H2-H3を主に使用することを推奨します。

# H1見出し(1ページに1つまで)

## H2見出し(メインセクション)

### H3見出し(サブセクション)

#### H4見出し(必要に応じて)

日本語見出しのサンプル

日本語の見出しも自動的にIDが生成され、ナビゲーションに表示されます。

### 日本語見出しのサンプル

English Heading Sample

English headings also work perfectly with automatic ID generation and navigation.

### English Heading Sample

Mixed 日英 Heading サンプル

日本語と英語が混在した見出しも問題なく動作します。

### Mixed 日英 Heading サンプル

テキスト装飾 - Text Formatting

基本的なテキスト装飾

太字テキスト斜体テキスト を使用できます。

インラインコード も使用可能で、技術用語や設定値を強調する際に便利です。

**太字テキスト**_斜体テキスト_ を使用できます。
`インラインコード` も使用可能です。

リンクの記述

外部リンク内部リンク を作成できます。

[外部リンク](https://example.com)
[内部リンク](/quickstart)
[アンカーリンク](#section-id)

コードブロック - Code Blocks

JavaScript Example

// JavaScript コードサンプル
function greetUser(name) {
  console.log(`Hello, ${name}!`)
  return `Welcome to our documentation, ${name}`
}

const user = 'Developer'
greetUser(user)

TypeScript Example

// TypeScript インターフェース定義
interface User {
  id: number
  name: string
  email: string
  isActive: boolean
}

// 関数の型定義
const createUser = (userData: Omit<User, 'id'>): User => {
  return {
    id: Math.floor(Math.random() * 1000),
    ...userData,
  }
}

JSON Configuration

{
  "name": "project-name",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^15.0.0",
    "react": "^18.0.0"
  }
}

Shell Commands

# プロジェクトのセットアップ
npm install
npm run dev

# Git操作
git add .
git commit -m "Add new feature"
git push origin main

リストの書き方 - List Writing

順序なしリスト - Unordered List

基本的な項目列挙に使用します:

  • 第一項目
  • 第二項目
  • ネストした項目
    • サブ項目1
    • サブ項目2
      • より深いネスト
- 第一項目
- 第二項目
- ネストした項目
  - サブ項目1
  - サブ項目2
    - より深いネスト

順序ありリスト - Ordered List

手順や優先順位がある場合に使用します:

  1. 最初のステップ
  2. 二番目のステップ
  3. ネストした手順
    1. サブステップA
    2. サブステップB
  4. 最終ステップ
1. 最初のステップ
2. 二番目のステップ
3. ネストした手順
   1. サブステップA
   2. サブステップB
4. 最終ステップ

チェックリスト - Task List

TODO項目や確認事項に便利です:

  • 完了した項目
  • もう一つの完了項目
  • 未完了の項目
  • 今後の予定項目
- [x] 完了した項目
- [x] もう一つの完了項目
- [ ] 未完了の項目
- [ ] 今後の予定項目

表の作成 - Table Creation

基本的な表

項目名説明必須
nameユーザー名
emailメールアドレス
age年齢-
| 項目名 | 説明           | 必須 |
| ------ | -------------- | ---- |
| name   | ユーザー名     | ✓    |
| email  | メールアドレス | ✓    |
| age    | 年齢           | -    |

APIレスポンス例

Status CodeDescriptionResponse
200Success{ "status": "ok", "data": {...} }
400Bad Request{ "error": "Invalid parameters" }
401Unauthorized{ "error": "Authentication required" }
500Server Error{ "error": "Internal server error" }
| Status Code | Description  | Response                                 |
| ----------- | ------------ | ---------------------------------------- |
| 200         | Success      | `{ "status": "ok", "data": {...} }`      |
| 400         | Bad Request  | `{ "error": "Invalid parameters" }`      |
| 401         | Unauthorized | `{ "error": "Authentication required" }` |
| 500         | Server Error | `{ "error": "Internal server error" }`   |

引用とハイライト - Quotes and Highlights

引用ブロック

これは重要な引用文です。公式ドキュメントからの引用や、重要な注意事項を記載する際に使用します。

複数行の引用も可能で、読みやすい形で表示されます。

> これは重要な引用文です。公式ドキュメントからの引用や、重要な注意事項を記載する際に使用します。
>
> 複数行の引用も可能で、読みやすい形で表示されます。

ネストした引用

メインの引用文です。

これはネストした引用で、さらに詳細な情報や補足説明に使用できます。

> メインの引用文です。
>
> > これはネストした引用で、さらに詳細な情報や補足説明に使用できます。

区切り線 - Horizontal Rules

セクションを明確に分離したい場合に使用します:


---

注意事項とベストプラクティス - Notes and Best Practices

見出し構造について

  • H1 (#) は1ページに1つまで
  • H2 (##) をメインセクションに使用
  • H3 (###) をサブセクションに使用
  • H4以下は必要に応じて使用(推奨はH3まで)

コードブロックの言語指定

コードブロックには必ず言語を指定してください:

```javascript
// 良い例
const example = 'Hello World'
```

```
// 悪い例(言語指定なし)
const example = "Hello World";
```

リンクの記述方法

  • 外部リンク: [表示テキスト](https://example.com)
  • 内部リンク: [表示テキスト](/path/to/page)
  • アンカーリンク: [表示テキスト](#section-id)

画像の追加

![代替テキスト](/images/sample.png)

高度な機能 - Advanced Features

HTMLタグの使用

MDX内では一部のHTMLタグも使用できます:

カスタムスタイルボックス

特別な装飾が必要な場合にHTMLとCSSを組み合わせて使用できます。

<div
  style={{
    padding: '16px',
    backgroundColor: '#f5f5f5',
    borderRadius: '8px',
    margin: '16px 0',
  }}
>
  <strong>カスタムスタイルボックス</strong>
  <br />
  特別な装飾が必要な場合にHTMLとCSSを組み合わせて使用できます。
</div>

変数の使用

MDXでは変数を定義して再利用できます:

プロジェクト名: 555GTADoc
バージョン: 1.0.0

export const projectName = '555GTADoc'
export const version = '1.0.0'

プロジェクト名: {projectName}  
バージョン: {version}

まとめ - Summary

このサンプルページで紹介した機能を参考に、読みやすく構造化された記事を作成してください。

記事作成時のチェックリスト

  • 適切な見出し構造(H1は1つ、H2-H3を主に使用)
  • コードブロックに言語指定
  • リンクの動作確認
  • 表の整列確認
  • 全体的な読みやすさの確認

これらのガイドラインに従って、質の高いドキュメントを作成してください。

このページは役に立ちましたか?