Markdown 作成ガイド
高品質な技術ドキュメントを作成するための完全ガイド
# Markdown 作成ガイド
> 高品質な技術ドキュメントを作成するための完全ガイド | v1.0.4
---
## YAML Frontmatter（必須）
すべてのドキュメントは YAML Frontmatter から始める必要があります：
```yaml
---
title: ドキュメントタイトル
slug: url-friendly-slug
category: カテゴリslug
tags: [タグ1, タグ2]
author: admin
sort: 1
description: 簡潔な説明（SEO に重要）
language: jp
notice: "💡 任意の通知バナー"
---
```
### フィールド説明
| フィールド | 必須 | 説明 |
|-----------|------|------|
| `title` | はい | ドキュメントタイトル |
| `slug` | はい | URL 識別子（英数字、ハイフン、アンダースコアのみ、最大 200 文字） |
| `category` | はい | カテゴリ slug（既存のものである必要があります） |
| `tags` | はい | タグ配列 `[tag1, tag2]` |
| `author` | はい | 著者名 |
| `sort` | いいえ | 並び順（数値、昇順、デフォルト 999） |
| `description` | いいえ | 検索結果のサマリー |
| `notice` | いいえ | 通知バナーテキスト |
| `language` | いいえ | 言語コード（zh/en/jp） |
::: warning
slug はファイル名と URL パスとして使用されるため、作成後に変更することはできません。
:::
---
## 基本 Markdown 構文
### 見出し
```markdown
# 一級見出し（1つのみ）
## 二級見出し
### 三級見出し
#### 四級見出し
```
### テキスト書式
```markdown
**太字** | *斜体* | ~~取り消し線~~ | ==ハイライト==
```
### リスト
```markdown
- 箇条書きリスト
- サブアイテム
1. 番号付きリスト
2. 2番目の項目
- [x] 完了したタスク
- [ ] 未完了のタスク
```
### 引用と区切り線
```markdown
> 引用テキスト
---
```
### リンク
```markdown
[内部リンク](/docs/slug)
[外部リンク](https://example.com)
[アンカーリンク](#section-id)
```
### テーブル
```markdown
| 列 1 | 列 2 | 列 3 |
|------|------|------|
| データ | データ | データ |
```
### 脚注
```markdown
これは脚注付きの文章です[^1]。
[^1]: これは脚注の内容で、ページ下部に表示されます。
```
脚注は自動的にドキュメント下部に区切り線付きで番号付き表示されます。
---
## コードブロック
### 基本コードブロック
````markdown
```bash
npm install
```
```javascript
console.log("Hello");
```
```json
{ "key": "value" }
```
````
### 対応言語
`bash`、`javascript`、`python`、`json`、`yaml`、`css`、`html`、`sql`、`go`、`java`、`rust`、`cpp`、`shell`、`dockerfile`、`nginx`
### タブ付きコードブロック
複数の連続するコードブロックをタブ切り替え表示にまとめます。コードブロック情報の後に `// [タブ名]` を追加します：
````markdown
```bash // [Bash]
npm install geowiki-cli
```
```python // [Python]
import requests
response = requests.get("https://api.example.com")
```
```javascript // [JavaScript]
fetch("https://api.example.com")
.then(res => res.json())
```
````
表示効果：コードブロック上部にタブボタンが表示され、クリックで異なる言語のコードに切り替えられます。
::: tip
タブ付きコードブロックは、同じ機能を異なる言語で実装する方法を示すのに最適です。
:::
---
## Mermaid ダイアグラム
`mermaid` 言語識別子を使用してフローチャート、シーケンス図、ガントチャートなどを作成します：
### フローチャート
````markdown
```mermaid
graph TD
A[開始] --> B{判定}
B -->|条件1| C[処理1]
B -->|条件2| D[処理2]
C --> E[終了]
D --> E
```
````
### シーケンス図
````markdown
```mermaid
sequenceDiagram
participant A as ユーザー
participant B as サーバー
A->>B: リクエスト送信
B->>A: レスポンス返却
```
````
### ガントチャート
````markdown
```mermaid
gantt
title プロジェクト計画
section フェーズ1
要件定義: 2026-01-01, 7d
設計: 2026-01-08, 5d
section フェーズ2
開発: 2026-01-13, 14d
テスト: 2026-01-27, 7d
```
````
### クラス図
````markdown
```mermaid
classDiagram
class User {
+String name
+String email
+login()
}
class Post {
+String title
+String content
+publish()
}
User --> Post : 書き込み
```
````
::: note
Mermaid ダイアグラムはダークモードに自動的に適応し、追加設定は不要です。
:::
---
## ECharts チャート
`echarts` 言語識別子を使用してインタラクティブなチャートを作成します：
### 棒グラフ
````markdown
```echarts
{
"title": { "text": "月間アクセス数" },
"tooltip": {},
"xAxis": { "data": ["1月", "2月", "3月", "4月", "5月", "6月"] },
"yAxis": {},
"series": [{ "name": "アクセス数", "type": "bar", "data": [120, 200, 150, 80, 70, 110] }]
}
```
````
### 折れ線グラフ
````markdown
```echarts
{
"title": { "text": "トレンド分析" },
"tooltip": { "trigger": "axis" },
"xAxis": { "type": "category", "data": ["月", "火", "水", "木", "金"] },
"yAxis": { "type": "value" },
"series": [{ "name": "データ", "type": "line", "data": [100, 150, 130, 180, 160] }]
}
```
````
### 円グラフ
````markdown
```echarts
{
"title": { "text": "アクセス元分布" },
"tooltip": { "trigger": "item" },
"series": [{
"name": "アクセス元",
"type": "pie",
"radius": "50%",
"data": [
{ "value": 335, "name": "直接アクセス" },
{ "value": 310, "name": "検索エンジン" },
{ "value": 234, "name": "ソーシャルメディア" }
]
}]
}
```
````
::: tip
ECharts チャートはインタラクティブ操作をサポートし、マウスオーバーで詳細データが表示されます。チャートはダークモードに自動的に適応します。
:::
---
## グリッドレイアウト
`:::grid` を使用してレスポンシブなグリッドレイアウトを作成します。画像やコンテンツブロックを並べて表示するのに適しています：
### 基本グリッド
```markdown
:::grid{cols=2}
コンテンツブロック 1
コンテンツブロック 2
:::
```
### カードスタイルグリッド
```markdown
:::grid{cols=3 style=card}
カードコンテンツ 1
カードコンテンツ 2
カードコンテンツ 3
:::
```
| パラメータ | 説明 | デフォルト |
|-----------|------|-----------|
| `cols` | 列数（1〜6） | 2 |
| `style` | スタイル（default / card） | default |
::: note
空行で区切られた各コンテンツブロックがグリッドセルになります。1〜6列をサポートします。
:::
---
## 拡張構文
### コールアウト（Callouts）
```markdown
::: note
補足説明情報。
:::
::: tip
役立つヒント。
:::
::: warning
重要な注意事項。
:::
::: danger
重要な安全情報。
:::
```
### FAQ ブロック
```markdown
::: faq
**Q: 質問1？**
回答1。
**Q: 質問2？**
回答2。
:::
```
### 数式
インライン数式：`$E=mc^2$`
ブロック数式：
```markdown
$$
\int_{a}^{b} f(x) dx = F(b) - F(a)
$$
```
### 埋め込み動画
```markdown
:::video[動画説明](https://bilibili.com/video/BVxxx)
:::
```
### 3D モデル
```markdown
:::model[モデル名](/media/model.step)
:::
```
### ファイルダウンロード
PDF、DOC などのファイルは自動的にダウンロードカードとして表示されます：
```markdown
[ユーザーマニュアル](/media/manual.pdf)
```
### 画像
画像は自動的にレスポンシブ表示され、alt テキストがキャプションとして表示されます：
```markdown
```
---
## コールアウトの種類
| 種類 | 用途 | ボーダー色 |
|------|------|-----------|
| `::: note` | 補足説明 | 青 |
| `::: tip` | ヒント・提案 | 緑 |
| `::: warning` | 注意事項 | 黄 |
| `::: danger` | 安全警告 | 赤 |
---
## よくある質問
**Q: slug は作成後に変更できますか？**
A: いいえ。slug はファイル名と URL パスとして使用されるため、変更は新しいドキュメントの作成と同じになります。
**Q: 現在の言語以外のドキュメントを編集するには？**
A: CLI で言語を指定します：`geo doc update --slug xxx --lang en`
**Q: 画像はどこに置きますか？**
A: `public/media/` ディレクトリに配置し、`/media/filename.ext` で参照します。
**Q: コードブロックに行番号を付けるには？**
A: システムが自動的に行番号を追加するため、手動設定は不要です。
**Q: タブ付きコードブロックは最大何タブまでサポートしていますか？**
A: 5つ以下を推奨します。多すぎると表示に影響します。
**Q: ECharts チャートはどのタイプをサポートしていますか？**
A: ECharts 5 のすべてのチャートタイプをサポートしています：棒グラフ、折れ線グラフ、円グラフ、散布図、レーダーチャート、ヒートマップなど。
---
*最終更新: 2026-06-22 | バージョン: v1.0.4*