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
手順や優先順位がある場合に使用します:
- 最初のステップ
- 二番目のステップ
- ネストした手順
- サブステップA
- サブステップB
- 最終ステップ
1. 最初のステップ
2. 二番目のステップ
3. ネストした手順
1. サブステップA
2. サブステップB
4. 最終ステップ
チェックリスト - Task List
TODO項目や確認事項に便利です:
- 完了した項目
- もう一つの完了項目
- 未完了の項目
- 今後の予定項目
- [x] 完了した項目
- [x] もう一つの完了項目
- [ ] 未完了の項目
- [ ] 今後の予定項目
表の作成 - Table Creation
基本的な表
| 項目名 | 説明 | 必須 |
|---|---|---|
| name | ユーザー名 | ✓ |
| メールアドレス | ✓ | |
| age | 年齢 | - |
| 項目名 | 説明 | 必須 |
| ------ | -------------- | ---- |
| name | ユーザー名 | ✓ |
| email | メールアドレス | ✓ |
| age | 年齢 | - |
APIレスポンス例
| 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" } |
| 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)
画像の追加

高度な機能 - 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を主に使用)
- コードブロックに言語指定
- リンクの動作確認
- 表の整列確認
- 全体的な読みやすさの確認
これらのガイドラインに従って、質の高いドキュメントを作成してください。