Skip to main content

高速なMarkdown変換のためのChrome拡張機能を試してください

GitHub Markdown ガイド：GitHub Flavored Markdown 完全マスター講座

開発者必須スキル：GitHub Flavored Markdown (GFM) の独自機能を深く学ぶ。タスクリスト、テーブル拡張、コード引用、数式表示などGitHub特有の機能を網羅。

公開日:
更新日:
guides.difficulty.中級
jagithub markdown, github flavored markdown, gfm, タスクリスト, githubドキュメント, 開発者ツール1PT1M中級TutorialTechnology

GitHub Markdown コンセプトイメージ

GitHub Markdown、特に GitHub Flavored Markdown（GFM）は、現代のソフトウェア開発や技術文書作成における標準ツールとして確立しました。世界最大のコードホスティングプラットフォームである GitHub は、開発者に強力なバージョン管理機能を提供するだけでなく、その独自の Markdown 実装を通じて、技術文書の作成と共同作業の方法に革命をもたらしました[1]。

現代のソフトウェア開発エコシステムにおいて、明確で正確かつメンテナンスしやすい文書は、プロジェクト成功の重要な要素の一つとなっています。GitHub Markdown は、従来の Markdown の簡潔さと可読性を引き継ぐだけでなく、開発者のニーズに応えた多数の拡張機能を追加しており、個人プロジェクトから企業レベルのアプリケーションまで不可欠な文書ツールとして活用されています。

GitHub Markdown の概要

GitHub Flavored Markdown とは

GitHub Flavored Markdown（GFM）は、GitHub が標準の CommonMark 仕様を基に開発した Markdown 方言で、ソフトウェア開発と技術協業のニーズに特化して設計されています[2]。従来の Markdown と比較して、GFM は元の簡潔さと可読性を維持しつつ、多くの実用的な拡張機能を追加しており、現代の開発ワークフローにおいて欠かせない存在となっています。

GFM の基本理念は、Markdown の本来の利点を保ちつつ、開発者により強力で専門的な文書作成能力を提供することです。この設計思想は複数の側面に現れています。第一に、GFM は標準 Markdown 構文と完全互換であり、既存文書のシームレスな移行を保証します。第二に、コードハイライト、タスクリスト、表など、開発者の実際のニーズに密接に関連した新機能を追加しています。最後に、すべての拡張機能は Markdown の簡潔さの原則に従っており、複雑な構文構造を避けています。

GitHub は公式に GFM を「GitHub.com および GitHub Enterprise でユーザーコンテンツをサポートする現在の Markdown 方言」と定義しています[3]。この定義は、GFM の実用性と普遍性を強調しています。GFM は単なる理論的な仕様ではなく、世界中の数百万の開発者によって実証された実際のツールなのです。

環境情報

  • OS: macOS
  • ブラウザ: Chrome 90+
  • Node.js: v16.14.0+

インストール手順

  1. Node.js バージョンの確認

    システムに Node.js 16.14.0 以降がインストールされていることを確認してください：

    node --version

  2. プロジェクトのクローン

    以下のコマンドでプロジェクトをローカルにクローンします：

    git clone https://github.com/user/repo.git

定義リストは標準的な Markdown の一部ではありませんが、一部の GitHub 環境でサポートされています：

用語 1
: これは用語 1 の定義です。

用語 2
: これは用語 2 の定義です。
複数行の内容を含めることができます。

リストのネストにはインデントの一貫性に注意が必要です。サブリストの項目は正しい階層構造を保つため、4 つのスペースまたは 1 つのタブでインデントする必要があります。

これらの基本構文をマスターすれば、GitHub Markdown を使用してプロフェッショナルなドキュメントを作成する基本的な能力を身につけたことになります。次に、GitHub 特有の拡張機能について詳しく見ていきましょう。これらの機能はあなたのドキュメントをより強力で実用的なものにしてくれます。

GitHub の特色機能

GitHub Flavored Markdown の真の価値は、ソフトウェア開発とチームコラボレーションのために特別に設計された独自の拡張機能にあります。これらの特色機能はドキュメントの表現力を高めるだけでなく、ドキュメントを GitHub のエコシステム全体と深く統合し、これまでにないコラボレーション体験を創造します。

タスクリストとプロジェクト管理

タスクリストは GFM で最も人気のある機能の一つで、シンプルなテキストをインタラクティブなプロジェクト管理ツールに変換します。この機能の強力な点は、単なる静的なドキュメント要素ではなく、GitHub の Issues や Pull Requests システムと深く統合された動的なツールであることです。

基本的なタスクリストの構文は非常にシンプルで、- [ ]で未完了のタスク、- [x]で完了したタスクを表します：

## プロジェクトマイルストーン v2.0

### コア機能開発

- [x] ユーザー認証システム
- [x] データベース設計
- [ ] API インターフェース開発
  - [x] ユーザー管理 API
  - [ ] データクエリ API
  - [ ] ファイルアップロード API
- [ ] フロントエンドインターフェース開発
- [ ] テストケース作成

### デプロイとリリース

- [ ] 本番環境設定
- [ ] パフォーマンステスト
- [ ] ドキュメント更新

GitHub の Issues や Pull Requests では、タスクリストは特別なインタラクティブ性を持っています。ユーザーはチェックボックスを直接クリックしてタスクの状態を切り替えることができ、これらの変更はそのコンテンツを表示しているすべてのユーザーインターフェースにリアルタイムで反映されます。さらに重要なのは、GitHub が Issue や Pull Request のタイトルの横にタスクの進捗状況（例："3 of 8 tasks completed"）を表示することです。

タスクリストの高度な応用として、Issue 番号との関連付けがあります。タスクの説明に Issue 番号を含めることで、タスクと具体的な作業項目との直接的なリンクを作成できます：

- [x] ユーザーログイン機能の実装 #123
- [ ] パスワードリセット機能の追加 #124
- [ ] ログインページ UI の最適化 #125

この関連付けは便利なナビゲーションを提供するだけでなく、関連する Issue がクローズされると自動的にタスクの状態が更新されます。参照されている Issue がクローズされると、対応するタスク項目が自動的に完了としてマークされ、この自動化によりプロジェクト管理の手作業が大幅に削減されます。

タスクリストはネスト構造もサポートしており、複雑なプロジェクトの分解に特に有用です：

- [ ] ユーザーモジュールのリファクタリング
  - [x] 既存コード構造の分析
  - [x] 新しいアーキテクチャの設計
  - [ ] 新機能の実装
    - [x] ユーザー登録
    - [ ] ユーザーログイン
    - [ ] パスワード管理
  - [ ] テストケースの作成
  - [ ] ドキュメントの更新

テーブルの高度な使い方

テーブル機能は GFM が標準 Markdown に対して行った重要な拡張で、構造化データの表示に強力なツールを提供します。GitHub のテーブル実装は基本的な行と列の構造をサポートするだけでなく、配置やフォーマットなどの高度な機能も提供します。

基本的なテーブル構文ではパイプ記号 | で列を区切り、2 行目にハイフン - を使用してヘッダーを定義します：

| 機能               | 状態   | 担当者  | 締切日     |
| ------------------ | ------ | ------- | ---------- |
| ユーザーログイン   | 完了   | Alice   | 2024-01-15 |
| データエクスポート | 進行中 | Bob     | 2024-01-20 |
| レポート生成       | 未開始 | Charlie | 2024-01-25 |

列の配置はコロンを使用して制御できます：

| 左揃え | 中央揃え | 右揃え |
| :----- | :------: | -----: |
| 内容   |   内容   |   内容 |

テーブル内容には他の Markdown 要素（リンク、太字、斜体、コードなど）を含めることができます：

| コンポーネント         |   状態    | ドキュメント                         | 備考                   |
| ---------------------- | :-------: | ------------------------------------ | ---------------------- |
| **ユーザーモジュール** |  ✅ 完了  | [API ドキュメント](./api/user.md)    | テスト済み             |
| _権限システム_         | 🚧 開発中 | [設計ドキュメント](./design/auth.md) | 来週完成予定           |
| `データベース`         | ❌ 未開始 | -                                    | ユーザーモジュール依存 |

複雑なテーブルの作成には HTML 構文を使用して、セル結合やカスタムスタイルなどのより高度な機能を実現できます：

<table>
  <thead>
    <tr>
      <th rowspan="2">機能モジュール</th>
      <th colspan="2">開発進捗</th>
      <th rowspan="2">担当者</th>
    </tr>
    <tr>
      <th>フロントエンド</th>
      <th>バックエンド</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>ユーザー管理</td>
      <td>100%</td>
      <td>100%</td>
      <td>Alice</td>
    </tr>
    <tr>
      <td>データ分析</td>
      <td>80%</td>
      <td>90%</td>
      <td>Bob</td>
    </tr>
  </tbody>
</table>

コードブロックとシンタックスハイライト

コード表示は技術文書のコア要件であり、GitHub Markdown はこの分野で業界をリードする機能を提供しています。基本的なコードブロックから高度なシンタックスハイライト、差分表示から行番号まで、GFM のコード機能はほぼすべての技術文書の要求を満たすことができます。

フェンス形式のコードブロックは推奨されるコード表示方法で、3 つのバッククォートでコードを囲みます：

```javascript
function calculateSum(a, b) {
  return a + b;
}

const result = calculateSum(5, 3);
console.log(`結果は: ${result}`);
```

シンタックスハイライトはプログラミング言語を指定することで実現され、GitHub は数百のプログラミング言語とマークアップ言語をサポートしています：

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# フィボナッチ数列の第10項を計算
result = fibonacci(10)
print(f"第10項の値は: {result}")
```

```sql
SELECT u.username, p.title, p.created_at
FROM users u
JOIN posts p ON u.id = p.user_id
WHERE p.created_at > '2024-01-01'
ORDER BY p.created_at DESC
LIMIT 10;
```

差分表示はコードレビューにおいて重要な機能で、diff 言語識別子を使用します：

```diff
function calculateTotal(items) {
-   let total = 0;
+   let total = 0.0;
    for (let item of items) {
-       total += item.price;
+       total += parseFloat(item.price);
    }
    return total;
}
```

自動リンクと参照

自動リンク機能はドキュメント内のリンク作成と保守を大幅に簡素化します。GitHub は URL、メールアドレス、Issue 番号、Pull Request 番号、コミットハッシュなど、複数のタイプの参照を自動的に認識し変換します。

URL 自動リンクは最も基本的な機能で、有効な URL は自動的にクリック可能なリンクに変換されます：

公式サイト https://example.com で詳細をご確認ください。
プロジェクトリポジトリ：https://github.com/user/repo

メールアドレスも自動的に mailto リンクに変換されます：

ご質問は [email protected] または [email protected] までお問い合わせください。

Issue と Pull Request の参照は GitHub 特有の強力な機能です。# 記号に番号を付けて、対応する Issue や Pull Request へのリンクを作成できます：

この機能は #123 で提案され、#124 で実装されました。関連する Pull Request は #125 です。

クロスリポジトリ参照は ユーザー名/リポジトリ名#番号 の形式を使用します：

この問題は facebook/react#12345 と類似しています。
microsoft/vscode#6789 の解決策を参考にしてください。

Issue と Pull Request テンプレート

GitHub では Issue と Pull Request 用のテンプレートを作成でき、これらのテンプレートは Markdown 形式を使用して、問題報告やコード貢献の品質を大幅に向上させることができます。

Issue テンプレートは .github/ISSUE_TEMPLATE/ ディレクトリに配置します：

---
name: バグ報告
about: 改善のためのバグ報告を作成
title: "[BUG] "
labels: "bug"
assignees: ""
---

## バグの説明

このバグを簡潔に説明してください。

## 再現手順

1. '...' に移動
2. '....' をクリック
3. '....' までスクロール
4. エラーを確認

## 期待される動作

期待される動作を明確に説明してください。

## 実際の動作

実際に起こったことを明確に説明してください。

## スクリーンショット

該当する場合は、問題を説明するスクリーンショットを追加してください。

## 環境情報

- OS: [例: iOS]
- ブラウザ: [例: chrome, safari]
- バージョン: [例: 22]

## 追加情報

問題に関するその他の情報をここに記入してください。

Pull Request テンプレートは .github/pull_request_template.md に配置します：

## 変更内容

この PR で行った変更を簡潔に説明してください。

## 変更タイプ

- [ ] バグ修正 (既存機能に影響しない修正)
- [ ] 新機能 (既存機能に影響しない追加)
- [ ] 破壊的変更 (既存機能に影響する修正または機能)
- [ ] ドキュメント更新

## テスト

- [ ] コードのテストを実施しました
- [ ] 必要なテストケースを追加しました
- [ ] 新規・既存のテストがすべてパスしました

## チェックリスト

- [ ] コードがプロジェクトのコーディング規約に準拠しています
- [ ] 自己レビューを実施しました
- [ ] 特に理解しにくい部分にコメントを追加しました
- [ ] 関連ドキュメントを更新しました
- [ ] 変更によって新たな警告が発生していません

## 関連 Issue

Close #(issue 番号)

Wiki ページ作成

GitHub Wiki はプロジェクトドキュメントサイトを簡単に作成できる機能です。Wiki ページは GFM 構文を使用し、ページ間リンクや複雑なドキュメント構造をサポートします。

Wiki のホームページは通常、ドキュメントのナビゲーションセンターとして機能します：

# プロジェクトドキュメント

プロジェクトドキュメントへようこそ！ここではプロジェクトの使用と貢献に必要なすべての情報を提供します。

## クイックナビゲーション

### ユーザーガイド

- [インストールガイド](Installation-Guide)
- [クイックスタート](Quick-Start)
- [API リファレンス](API-Reference)
- [設定オプション](Configuration)

### 開発者ガイド

- [開発環境構築](Development-Setup)
- [コーディング規約](Coding-Standards)
- [テストガイド](Testing-Guide)
- [リリースプロセス](Release-Process)

### その他リソース

- [FAQ](FAQ)
- [トラブルシューティング](Troubleshooting)
- [変更履歴](Changelog)
- [ロードマップ](Roadmap)

Wiki ページ間のリンクには二重角括弧構文を使用します：

詳細は [[API リファレンス]] ページを参照してください。
インストールに関する問題は [[トラブルシューティング|Troubleshooting]] ページをご覧ください。

GitHub Pages 連携

GitHub Pages を使用すると、リポジトリから直接静的ウェブサイトを公開でき、Markdown ドキュメントと完璧に連携します。適切な設定により、プロジェクトドキュメントをプロフェッショナルなドキュメントサイトに変換できます。

Jekyll は GitHub Pages のデフォルト静的サイトジェネレーターで、Markdown ファイルの自動変換をサポートします：

---
layout: default
title: API ドキュメント
permalink: /api/
---

# API ドキュメント

こちらは API の詳細ドキュメントです...

## 認証

すべての API リクエストには認証トークンが必要です...

_config.yml ファイルでサイトの基本情報を設定できます：

title: プロジェクトドキュメント
description: プロジェクトの公式ドキュメントサイト
baseurl: "/project-docs"
url: "https://username.github.io"

markdown: kramdown
highlighter: rouge
theme: minima

plugins:
  - jekyll-feed
  - jekyll-sitemap

自動化とワークフロー

GitHub Actions は Markdown ドキュメントと組み合わせて、強力な自動化ワークフローを作成できます。例えば、ドキュメントリンクの有効性チェック、API ドキュメントの自動生成、外部システムへのドキュメント同期などが可能です。

ドキュメントリンクチェックのワークフロー：

name: ドキュメントリンクチェック

on:
  push:
    paths:
      - "**/*.md"
  pull_request:
    paths:
      - "**/*.md"

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Markdown リンクチェック
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: "yes"
          use-verbose-mode: "yes"

目次自動生成のワークフロー：

name: 目次更新

on:
  push:
    branches: [main]
    paths:
      - "docs/**/*.md"

jobs:
  update-toc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: 目次生成
        run: |
          npm install -g markdown-toc
          markdown-toc -i README.md
      - name: 変更をコミット
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add README.md
          git commit -m "目次を自動更新" || exit 0
          git push

これらの高度な応用テクニックにより、GitHub Markdown の潜在能力を最大限に活用し、プロフェッショナルで効率的、メンテナンスしやすいプロジェクトドキュメントを作成できます。次に、実際のプロジェクト事例を通じて、これらのテクニックの具体的な応用を紹介します。

実践プロジェクト事例

GitHub ワークフロー統合図

実際のプロジェクト事例の分析を通じて、GitHub Markdown が実環境でどのように活用されるかをより深く理解できます。以下の事例では、異なる種類のプロジェクトと活用シナリオを取り上げ、GFM の強力な機能とベストプラクティスを紹介します。

オープンソースプロジェクトのドキュメント事例

React プロジェクトを例として、大規模なオープンソースプロジェクトが GitHub Markdown を使用して複雑な情報構造をどのように整理しているかを見てみましょう。React のドキュメント戦略は深く分析し学習する価値があります。

React プロジェクトの README は明確な階層構造を採用し、プロジェクト紹介から始まって技術的な詳細へと段階的に進んでいきます。その見出し構成は論理的な進行原則に従っています：

# React

React はユーザーインターフェースを構築するための JavaScript ライブラリです。

## 特徴

- **宣言的**: React はインタラクティブな UI を作成することを容易にします...
- **コンポーネント化**: 自身の状態を管理するコンポーネントを構築します...
- **一度学べばどこでも書ける**: 技術スタックについて何も仮定しません...

## インストール

React は段階的に導入できるように設計されているため、必要に応じて React を使用することができます。

### オンラインで React を試す

React を試したい場合は、オンラインコードエディタを使用できます...

### React をウェブサイトに追加

React を HTML ページに追加するには、1 分ほどかかります...

### 新しい React アプリケーションを作成

新しい React プロジェクトを開始するときは、シンプルな HTML ページ...

コード例の整理は特に重要です。React ドキュメントは、各概念の紹介後に実行可能なコード例を提供し、それらの例は読者が直接使用できるように設計されています：

### シンプルなコンポーネント

React コンポーネントは `render()` メソッドを実装し、入力データを受け取り、表示する内容を返します。

```jsx
class HelloMessage extends React.Component {
  render() {
    return <div>Hello {this.props.name}</div>;
  }
}

ReactDOM.render(
  <HelloMessage name="Taylor" />,
  document.getElementById("hello-example")
);
```

この例では、類似 XML の構文である JSX を使用しています...


リンク戦略も重要です。React ドキュメントは、内部リンクと外部リンクの組み合わせを巧みに使用し、ドキュメントの完全性を保ちながら、深い学習の道筋を提供しています

```markdown
## React を学ぶ

人々は異なる背景を持ち、異なる学習スタイルを持っています。理論的な方法と実践的な方法のどちらを好むかにかかわらず、この部分がお役に立つことを願っています。

- もし**実践的に学びたい**場合は、[実践的なチュートリアル](https://reactjs.org/tutorial/tutorial.html)から始めてください。
- もし**概念を学びたい**場合は、[主要概念ガイド](https://reactjs.org/docs/hello-world.html)から始めてください。

React は不慣れな技術であり、確かに学習曲線があります。練習と少しの忍耐を持つことで、あなた*は*それを掌握するでしょう。

技術ブログの執筆事例

技術ブログは GitHub Markdown の表現力を示す別の重要なシナリオです。GitHub 公式ブログの記事を例として、GFM を使用して魅力的な技術コンテンツを作成する方法を学ぶことができます。

技術ブログ記事の構造は通常、序論、問題の説明、解決策、コード例、およびまとめで構成されています。各部分には特定の執筆技術があります：

# GitHub Actions のパフォーマンスを向上させる 5 つのテクニック

現代のソフトウェア開発では、CI/CD パイプラインのパフォーマンスは開発効率に直接影響します。この記事では、GitHub Actions の実行速度を大幅に向上させる 5 つの実用的なテクニックを共有します。

## 背景について

プロジェクトの規模が増大するにつれて、CI/CD パイプラインの実行時間が長くなっていることがわかりました...

## テクニック 1：依存関係のキャッシュ最適化

依存関係のインストールは通常、CI プロセスで最も時間がかかるステップの 1 つです。適切なキャッシュ設定を行うことで、ビルド時間を大幅に短縮できます。

```yaml
- name: Node.js 依存関係のキャッシュ
  uses: actions/cache@v2
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-
```

この設定の重要な点は、`package-lock.json` のハッシュ値をキャッシュキーとして使用することです...

コード例の表示には、特にコンテキストの提供に注意が必要です。優れた技術ブログはコードだけでなく、コードの作用と原理を説明します：

## テクニック 2：タスクの並行実行

GitHub Actions はタスクの並行実行をサポートしており、この特性を適切に利用することで、総実行時間を大幅に短縮できます。

```yaml
jobs:
  test:
    strategy:
      matrix:
        node-version: [14, 16, 18]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Node.js ${{ matrix.node-version }} を使用
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test
```

マトリックス戦略を使用すると、複数の Node.js バージョンでテストを並行実行できます。これにより、時間を節約し、テストカバレッジを向上させることができます。

### パフォーマンスの比較

最適化前後のパフォーマンスの比較を見てみましょう：

| 最適化プロジェクト     | 最適化前 | 最適化後 | 向上率 |
| ---------------------- | -------- | -------- | ------ |
| 依存関係のインストール | 3 分     | 30 秒    | 83%    |
| テストの実行           | 8 分     | 3 分     | 62%    |
| 総実行時間             | 15 分    | 6 分     | 60%    |

チーム協働規範事例

大規模なチームの協働には明確な規範とプロセスが必要です。GitHub Markdown はこれらの規範の策定と保守に重要な役割を果たします。以下は、完全なチーム協働規範の例です：

# チーム協働規範

## コードの提出規範

### 提出情報の形式

すべての提出情報は以下の形式に従う必要があります：

```

<タイプ>(<範囲>): <説明>

<詳細説明>

<関連 Issue>

```

#### タイプの説明

- `feat`: 新機能
- `fix`: Bug 修正
- `docs`: ドキュメント更新
- `style`: コード形式調整
- `refactor`: コードのリファクタリング
- `test`: テスト関連
- `chore`: ビルドプロセスまたは補助ツールの変更

#### 例

```

feat(user): ユーザーのアバターのアップロード機能を追加

- JPG、PNG 形式をサポート
- 自動圧縮とクロップ
- アップロードの進行状況を表示

#123 を閉じる
```

ブランチ管理戦略

Git Flow ワークフローを採用しています：

graph LR
    A[main] --> B[develop]
    B --> C[feature/user-avatar]
    B --> D[feature/payment]
    C --> B
    D --> B
    B --> E[release/v2.0]
    E --> A
    E --> B
  • main: 本番環境ブランチ
  • develop: 開発環境ブランチ
  • feature/*: 機能開発ブランチ
  • release/*: リリース準備ブランチ
  • hotfix/*: 緊急修正ブランチ

コードレビューのワークフロー

  1. Pull Request の作成

    • PR テンプレートを使用
    • 関連するラベルを追加
    • レビューアを指定

  2. レビューの確認リスト

    • コードが規範に従っている
    • テストカバレッジが達成されている
    • ドキュメントが更新されている
    • セキュリティの脅威がない

  3. マージ要求

    • 少なくとも 2 人のレビューが承認されている
    • すべての CI チェックが合格している
    • 競合がない

タスクの割り当てと追跡には、GitHub の Issues と Projects 機能を使用します：

## プロジェクト管理

### スプリントの計画

各スプリントの周期は 2 週間で、GitHub Projects を使用してタスク管理を行います。

#### Sprint 1 (2024-01-01 ~ 2024-01-14)

**目標**: ユーザーモジュールの核心機能を完成させる

**タスクの割り当て**:

- [ ] ユーザーの登録機能 (@alice) #101
  - [ ] フロントエンドのインターフェース設計
  - [ ] バックエンドの API 実装
  - [ ] メールの検証機能
- [ ] ユーザーのログイン機能 (@bob) #102
  - [ ] ログインフォーム
  - [ ] 認証
  - [ ] ログイン状態を記憶
- [ ] パスワードのリセット機能 (@charlie) #103
  - [ ] リセットプロセスの設計
  - [ ] メールの送信機能
  - [ ] セキュリティの検証

**受け入れ基準**:

- すべての機能がテストに合格している
- コードカバレッジ > 80%
- パフォーマンステストに合格している
- ドキュメントが完全である

### 毎日のスタンドアップ会議の記録

#### 2024-01-03

**昨日の完了事項**:

- @alice: ユーザーの登録インターフェース設計を完成させる
- @bob: ログイン API の基礎フレームワークを構築する
- @charlie: パスワードのリセットのベストプラクティスを調査する

**今日の計画**:

- @alice: 登録フォームの検証を実装する
- @bob: ログインロジックを実装する
- @charlie: パスワードのリセットプロセスの開発を開始する

**問題**:

- メールサービスの設定には運用サポートが必要 (@devops)
- UI デザインにはさらなる確認が必要 (@design-team)

プロジェクト展示ページ事例

プロジェクト展示ページは、限られたスペースで最大の情報量を伝え、視覚的な魅力を維持する必要があります。以下は、優れたプロジェクト展示ページの構造です：

<div align="center">

# 🚀 ProjectName

**プロジェクトの核心価値を一言で説明**

[![Build Status](https://img.shields.io/github/workflow/status/user/repo/CI)](https://github.com/user/repo/actions)
[![Coverage](https://img.shields.io/codecov/c/github/user/repo)](https://codecov.io/gh/user/repo)
[![Version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name)
[![License](https://img.shields.io/github/license/user/repo)](LICENSE)

[🎯 クイックスタート](#クイックスタート) • [📖 ドキュメント](https://docs.example.com) • [🎮 オンラインデモ](https://demo.example.com) • [💬 ディスカッション](https://github.com/user/repo/discussions)

![プロジェクトデモ](github_features_comparison.png)

</div>

---

## ✨ 特徴

<table>
<tr>
<td width="50%">

### 🎯 コア機能

- **スマート分析**: AI 駆動のデータ分析
- **リアルタイム同期**: ミリ秒単位のデータ同期
- **可視化**: 豊富なチャートとダッシュボード

</td>
<td width="50%">

### 🛠️ 技術的特徴

- **高性能**: 百万レベルのデータ処理をサポート
- **拡張可能**: マイクロサービスアーキテクチャ設計
- **安全**: エンタープライズレベルのセキュリティ保証

</td>
</tr>
</table>

## 🚀 クイックスタート

### インストール

```bash
# 使用 npm
npm install project-name

# 使用 yarn
yarn add project-name

# 使用 pnpm
pnpm add project-name
```

### 基本的な使い方

```javascript
import { ProjectName } from "project-name";

// インスタンスを作成
const app = new ProjectName({
  apiKey: "your-api-key",
  endpoint: "https://api.example.com",
});

// 使用開始
const result = await app.analyze(data);
console.log(result);
```

## 📊 パフォーマンス

| 指標            | 数値    | 説明                       |
| --------------- | ------- | -------------------------- |
| 🚀 応答時間     | < 100ms | 99% リクエスト応答時間     |
| 📈 スループット | 10k QPS | 単一インスタンスの処理能力 |
| 💾 メモリ使用量 | < 50MB  | 実行時メモリ使用           |
| 🔧 可用性       | 99.9%   | サービスの可用性保証       |

## 🏗️ アーキテクチャ設計

```mermaid
graph TB
    A[クライアント] --> B[API ゲートウェイ]
    B --> C[認証サービス]
    B --> D[ビジネスサービス]
    D --> E[データベース]
    D --> F[キャッシュ]
    D --> G[メッセージキュー]
```

## 🤝 貢献

私たちはすべての形式的貢献を歓迎します！

- 🐛 [バグを報告](https://github.com/user/repo/issues/new?template=bug_report.md)
- 💡 [提案を提出](https://github.com/user/repo/issues/new?template=feature_request.md)
- 📖 [ドキュメントを改善](https://github.com/user/repo/blob/main/CONTRIBUTING.md)
- 💻 [コードを提出](https://github.com/user/repo/blob/main/CONTRIBUTING.md)

## 📄 ライセンス

本プロジェクトは [MIT ライセンス](LICENSE) でオープンソースです。

---

<div align="center">

**⭐ このプロジェクトがあなたに役立つ場合は、Star をください！**

[GitHub](https://github.com/user/repo) • [公式サイト](https://example.com) • [ドキュメント](https://docs.example.com) • [ブログ](https://blog.example.com)

</div>

ツールとリソース

適切なツールを選択することで、GitHub Markdown の作成効率と品質を大幅に向上させることができます。エディタからプレビューツール、自動化スクリプトからオンラインサービスまで、豊富なツールエコシステムは GFM の使用を強力にサポートします。

エディタの推奨と設定

Visual Studio Code は、最も人気のある Markdown エディタの 1 つであり、GFM の作成に対して全面的なサポートを提供します。

推奨の VS Code プラグイン設定：

{
  "recommendations": [
    "yzhang.markdown-all-in-one",
    "shd101wyy.markdown-preview-enhanced",
    "davidanson.vscode-markdownlint",
    "bierner.github-markdown-preview",
    "mushan.vscode-paste-image"
  ]
}

Markdown All in One プラグインは、完全な Markdown 作成体験を提供します：

  • 自動目次生成
  • 表のフォーマット
  • ショートカットキーのサポート
  • 数学公式のプレビュー

設定例：

{
  "markdown.extension.toc.levels": "2..6",
  "markdown.extension.toc.orderedList": false,
  "markdown.extension.list.indentationSize": "adaptive",
  "markdown.extension.tableFormatter.enabled": true
}

Typora は、所見即所得の編集体験を提供する優れた選択肢です：

  • リアルタイムプレビュー
  • テーマカスタマイズ
  • 画像管理
  • エクスポート機能

Obsidian は、知識管理とドキュメントネットワークの構築に特に適しています：

  • 双方向リンク
  • 図譜ビュー
  • プラグインシステム
  • ローカルストレージ

プレビューとデバッグツール

GitHub スタイルのプレビューは、ドキュメントが GitHub 上で正しく表示されることを確保するために重要です。以下のツールは正確なプレビューを提供できます：

Grip は、GitHub スタイルのプレビューをローカルで提供するコマンドラインツールです：

# インストール
pip install grip

# 使用する
grip README.md

Markdown Preview Enhanced プラグインは、複数のプレビュースタイルをサポートします：

---
html:
  embed_local_images: true
  embed_svg: true
print_background: true
---

# ドキュメントのタイトル

内容...

オンラインプレビューツール：

自動化ツール

自動化ツールは、ドキュメントの保守効率を大幅に向上させ、手動作業のエラーを削減できます。

Markdown TOC 自動生成目次：

# インストール
npm install -g markdown-toc

# 使用する
markdown-toc -i README.md

Markdownlint 構文チェック：

# インストール
npm install -g markdownlint-cli

# 使用する
markdownlint *.md

設定ファイル .markdownlint.json：

{
  "MD013": false,
  "MD033": {
    "allowed_elements": ["img", "br", "div", "table", "tr", "td", "th"]
  },
  "MD041": false
}

Pre-commit hooks 確保するためのコミット：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.32.2
    hooks:
      - id: markdownlint
        args: ["--fix"]

学習リソースの推奨

公式ドキュメント：

オンラインチュートリアル：

実践プロジェクト：

  • 既存のプロジェクトの README を改善
  • 個人の技術ブログを作成
  • オープンソースプロジェクトのドキュメントを作成
  • チームの知識ベースを構築

ベストプラクティスガイド

GitHub Markdown チートシート

GitHub Markdown は、長年の発展と実践により、成熟したベストプラクティスを形成しました。これらの実践は、ドキュメントの品質を向上させ、チームのコラボレーション効率を改善します。

ドキュメント構造設計原則

レイヤーが明確は優れたドキュメントの基礎です。タイトルは明確な階層構造を形成し、ジャンプレベルを使用しないでください：

# レベル 1 のタイトル - ドキュメントのトピック

## レベル 2 のタイトル - 主な章

### レベル 3 のタイトル - 具体的な内容

#### レベル 4 のタイトル - 詳細な説明

情報密度が適切は、各段落が 1 つのトピックに集中することを意味し、情報過剰を避けます：

## インストールガイド

### システム要件

このソフトウェアは以下のシステム環境が必要です：

- Node.js 16.0 またはそれ以上
- npm 7.0 またはそれ以上
- 少なくとも 2GB の可用メモリ

### インストール手順

1. **ソースコードをダウンロード**

   GitHub リポジトリから最新のコードをクローンします：

   ```bash
   git clone https://github.com/user/repo.git
   cd repo
   ```

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

   npm を使用してプロジェクトの依存関係をインストールします：

   ```bash
   npm install
   ```

コードサンプルの規範

コードサンプルは完全に実行可能である必要があり、重要な部分を省略しないでください：

## API 使用例

### 完全な例

```javascript
// 必要なモジュールをインポート
const { APIClient } = require("api-client");
const config = require("./config");

// クライアントインスタンスを作成
const client = new APIClient({
  apiKey: config.API_KEY,
  baseURL: "https://api.example.com/v1",
});

// 非同期関数の例
async function getUserData(userId) {
  try {
    const response = await client.users.get(userId);
    console.log("ユーザーデータ:", response.data);
    return response.data;
  } catch (error) {
    console.error("ユーザーデータの取得に失敗しました:", error.message);
    throw error;
  }
}

// 使用例
getUserData("12345")
  .then((user) => {
    console.log(`ようこそ, ${user.name}!`);
  })
  .catch((error) => {
    console.error("操作に失敗しました:", error);
  });
```

エラー処理は、サンプルに体現する必要があります：

### エラー処理のベストプラクティス

```javascript
// 推奨されるエラー処理方法
try {
  const result = await api.processData(data);

  if (!result.success) {
    throw new Error(`処理に失敗しました: ${result.error}`);
  }

  return result.data;
} catch (error) {
  // エラーを記録
  console.error("データ処理エラー:", error);

  // エラータイプに応じて異なる処理
  if (error.code === "RATE_LIMIT") {
    // 1 秒後に再試行
    await new Promise((resolve) => setTimeout(resolve, 1000));
    return api.processData(data);
  }

  // 他のエラーを再スロー
  throw error;
}
```

リンク管理戦略

内部リンクは、相対パスを使用する必要があり、リポジトリの移動時にリンクが依然として有効であることを確認してください：

詳細については、以下を参照してください：

- [インストールガイド](./docs/installation.md)
- [API ドキュメント](./docs/api/README.md)
- [よくある質問](./FAQ.md)

外部リンクは、定期的に有効性を確認する必要があり、引用式リンクを使用することをお勧めします：

より多くの学習リソース：

- [公式ドキュメント][official-docs]
- [コミュニティフォーラム][community]
- [ビデオチュートリアル][tutorials]

[official-docs]: https://example.com/docs
[community]: https://community.example.com
[tutorials]: https://youtube.com/playlist/example

画像とメディアの使用

画像の最適化は、ドキュメントの読み込み速度に重要です：

<!-- 推奨：適切なサイズの画像を使用 -->

![功能截图](github_markdown_cheatsheet.png)

<!-- 推奨しない：過大なオリジナル画像を使用 -->

![功能截图](github_workflow_integration.png)

代替テキストは、画像の内容を説明し、アクセシビリティを向上させる必要があります：

![ユーザーのログイン画面、ユーザー名とパスワードの入力ボックス、およびログインボタン](github_features_comparison.png)

バージョン管理と保守

変更履歴は、ドキュメントの重要な変更を詳細に記録する必要があります：

## 更新日志

### [2.1.0] - 2024-01-15

#### 新規追加

- API 認証章節を追加
- エラー処理の例を追加
- パフォーマンスの最適化の提案を追加

#### 変更

- インストールガイドを更新し、Node.js 18 をサポート
- コードサンプルの可読性を改善
- ドキュメントの構造を最適化

#### 修正

- リンクのエラーを修正
- 過去のスクリーンショットを更新
- コードサンプルの構文エラーを修正

ドキュメントレビューのプロセスは、品質を確保するために重要です：

## ドキュメントレビューのリスト

### 内容レビュー

- [ ] 情報の正確性
- [ ] 論理の完全性
- [ ] サンプルの実行性
- [ ] リンクの有効性

### フォーマットレビュー

- [ ] タイトルの階層が正しい
- [ ] コードブロックの構文ハイライト
- [ ] 画像の表示が正常
- [ ] テーブルのフォーマットが規範

### ユーザーエクスペリエンス

- [ ] ナビゲーションが明確
- [ ] 検索が使いやすい
- [ ] モバイル端末の適合
- [ ] 読み込み速度が合理

トラブルシューティングとよくある質問

GitHub Markdown を使用する際、ユーザーはよくある問題に遭遇します。これらの問題の解決方法を理解することで、作業効率を大幅に向上させることができます。

レンダリング問題の解決

テーブルの表示が異常は、通常、フォーマットが規範でないために発生します：

<!-- エラー：表頭の区切り行が不足 -->

| 列 1 | 列 2 |
| データ 1 | データ 2 |

<!-- 正しい：完全なテーブル構造を含む -->

| 列 1     | 列 2     |
| -------- | -------- |
| データ 1 | データ 2 |

コードブロックの構文ハイライトが表示されない：

<!-- エラー：言語識別子のスペルが間違っている -->

```javascirpt
console.log('Hello');
```

<!-- 正しい：正しい言語識別子を使用 -->

```javascript
console.log("Hello");
```

タスクリストが相互作用しない：

<!-- エラー：スペースが不足 -->

-[x] 完了したタスク -[ ] 未完了のタスク

<!-- 正しい：必要なスペースを含む -->

- [x] 完了したタスク
- [ ] 未完了のタスク

互換性の問題

異なるプラットフォームの違いは特に注意する必要があります：

機能 GitHub GitLab Bitbucket ソリューション
タスクリスト ✅ ✅ ❌ 標準リストを使用
テーブル ✅ ✅ ✅ 一般的なサポート
数学公式 ❌ ✅ ❌ 画像を使用して代替
Mermaid 図表 ✅ ✅ ❌ 画像の代替を提供

モバイル端末の表示最適化：

<!-- 推奨：レスポンシブテーブルを使用 -->
<div style="overflow-x: auto;">

| 長い列タイトル 1 | 長い列タイトル 2 | 長い列タイトル 3 |
| ---------------- | ---------------- | ---------------- |
| データ 1         | データ 2         | データ 3         |

</div>

パフォーマンスの最適化の提案

大きなドキュメントの分割：

# メインドキュメント

## 概要

簡単な説明...

## 詳細な内容

- [インストールガイド](./installation.md)
- [設定説明](./configuration.md)
- [API リファレンス](./api-reference.md)
- [トラブルシューティング](./troubleshooting.md)

画像の遅延読み込み：

<!-- HTML タグを使用して遅延読み込みを実現 -->
<img
  src="github_markdown_hero.png"
  data-src="github_features_comparison.png"
  loading="lazy"
  alt="描述"
/>

リンクチェックの自動化：

# GitHub Actions 工作流
name: リンクチェック
on:
  schedule:
    - cron: "0 0 * * 0" # 毎週1回チェック
jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: gaurav-nelson/github-action-markdown-link-check@v1

結論

GitHub Flavored Markdown は、現代のソフトウェア開発において不可欠なツールになりました。シンプルなプロジェクト説明から複雑な技術ドキュメント、個人のノートからチームのコラボレーションまで、GFM は強力で柔軟なソリューションを提供します。

このガイドを通じて、以下のことを理解しているはずです：

  1. 基礎的な構文の熟練：タイトルからリンク、リストからコードブロックまで、各要素にはそれぞれの最適な使用シーンがあります。

  2. GitHub の特徴的な機能の深い適用：タスクリスト、テーブル、自動リンクなどの機能により、ドキュメントを GitHub のエコシステムに深く統合します。

  3. 高度な技術の実践的な適用：README の最適化、テンプレート設計、自動化されたワークフローなどの技術により、ドキュメントの専門性と保守効率を向上させます。

  4. 最適な実践の体系的な理解：構造設計からパフォーマンスの最適化、チームのコラボレーションからバージョン管理まで、完全なドキュメント管理システムを形成します。

GitHub Markdown の価値は、その技術的な特性だけでなく、開発者間のコミュニケーションとコラボレーションを促進することです。優れたドキュメントはプロジェクトの成功の重要な要因であり、GFM はそのようなドキュメントの作成に理想的なツールを提供します。

技術は常に進化し、GitHub Markdown もそれに追随して進化しています。新しい機能と特性が追加され、それによりより強力で使いやすくなっています。学習を続け、実践を重ね、最新の発展動向をチェックすることで、この重要なツールの最新の機能を常に把握することができます。

最後に、ドキュメントの核心はユーザーに価値を提供することです。どんな高度な技術を使用しても、ユーザーのニーズを中心に、明確で正確で有用な内容を作成する必要があります。GitHub Markdown は単なるツールであり、真の価値はあなたが伝えたい知識と情報にあります。

Markdown のスキルをさらに向上させたい場合は、以下のような関連するチュートリアルを継続的に学習することをお勧めします：Markdown 高度な技術 は、より高度な適用技術を提供し

参考資料

[1] GitHub. "GitHub Flavored Markdown Spec." GitHub, 2019. https://github.github.com/gfm/

[2] CommonMark. "CommonMark Spec." CommonMark, 2021. https://spec.commonmark.org/

[3] GitHub Docs. "Basic writing and formatting syntax." GitHub, 2024. https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

[4] Gruber, John. "Markdown: Syntax." Daring Fireball, 2004. https://daringfireball.net/projects/markdown/syntax

[5] GitHub. "Working with advanced formatting." GitHub Docs, 2024. https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting

[6] Stack Overflow. "GitHub Flavored Markdown Questions." Stack Overflow, 2024. https://stackoverflow.com/questions/tagged/github-flavored-markdown

[7] Mozilla Developer Network. "HTML elements reference." MDN Web Docs, 2024. https://developer.mozilla.org/en-US/docs/Web/HTML/Element

[8] W3C. "HTML Living Standard." WHATWG, 2024. https://html.spec.whatwg.org/

[9] GitHub Community. "GitHub Community Forum." GitHub, 2024. https://github.community/

[10] Atlassian. "Markdown syntax guide." Atlassian Documentation, 2024. https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html

さらなる機能を探索

学習した内容を実践するためにツールを使用しましょう。

オンラインエディターHTML変換ツール