# Markdown 執筆ガイド > GEO Wiki Pro で高品質な技術ドキュメントを作成するための完全ガイド --- ## 概要 GEO Wiki Pro は Markdown をドキュメント執筆形式として使用します。各ドキュメントは YAML Frontmatter で始まり、本文は標準 Markdown 構文と拡張構文をサポートします。 このドキュメントでは執筆規範、ベストプラクティス、よくある注意事項を説明します。 --- ## YAML Frontmatter すべてのドキュメントは YAML Frontmatter で始まることが**必須**です。`---` で囲みます： ```yaml --- title: CAN Bus Protocol slug: can-bus-protocol category: can-motion tags: [can-bus, protocol] author: admin sort: 1 description: Brief description for search results --- ``` ### 必須フィールド | フィールド | 説明 | 例 | |-----------|------|-----| | `title` | ドキュメントタイトル | `CAN Bus Protocol` | | `slug` | URL 識別子（英数字、ハイフン、アンダースコアのみ） | `can-bus-protocol` | | `category` | カテゴリスラッグ（既存であること） | `can-motion` | | `tags` | タグ配列 | `[can-bus, protocol]` | | `author` | 著者名 | `admin` | ### オプションフィールド | フィールド | 説明 | 例 | |-----------|------|-----| | `sort` | ソート値（数字、昇順、デフォルト 999） | `1` | | `description` | 検索結果サマリー | `CAN bus overview...` | | `notice` | 通知バナーテキスト | `This is a beta feature.` | | `published_at` | 公開時刻 | `2026-05-20T10:30:00Z` | | `updated_at` | 更新時刻 | `2026-06-01T15:00:00Z` | ### スラッグルール - `/^[\w-]+$/` に一致すること（英数字、ハイフン、アンダースコアのみ） - 最大長：200 文字 - URL 互換性のために ASCII のみのスラッグを推奨 - `..`、`/`、`\`、`\0` を含めることはできない - システムが自動的にスラッグの重複をチェック ::: warning スラッグはファイル名と URL パスとして使用されるため、一度作成すると変更できません。簡潔で意味のあるスラッグを選択してください。 ::: --- ## 共有フィールドと独立フィールド ### 共有フィールド（クロス言語同期） 以下のフィールドはすべての言語バージョン間で自動的に同期： - `category` - `tags` - `author` - `sort` ある言語の共有フィールドを更新すると、`syncSharedFields()` が自動的にこれらの値を他の言語バージョンにブロードキャストします。 ### 独立フィールド（各言語独立） - `title` - `description` - `content` - `notice` - `updated_at` - `published_at` ::: note 多言語ドキュメントを作成する際は、各言語の独立フィールドのコンテンツのみを設定してください。共有フィールドは一度だけ設定すれば済みます。 ::: --- ## 見出し階層 ```markdown # H1 見出し（ドキュメントタイトル、ドキュメントあたり 1 つだけ） ## H2 見出し（メインセクション） ### H3 見出し（サブセクション） #### H4 見出し（より詳細な分類） ``` **ベストプラクティス：** - ドキュメントあたり `#` 見出しは 1 つだけ使用 - ドキュメント構造の構築に `##` と `###` を使用 - 見出しレベルをスキップしない（例：`##` から直接 `####` へ） --- ## テキストフォーマット ### 強調 ```markdown **太字テキスト** *斜体テキスト* ~~取り消し線テキスト~~ ``` ### リスト **順序なしリスト：** ```markdown - 最初のアイテム - 2 番目のアイテム - サブアイテム - サブアイテム ``` **順序付きリスト：** ```markdown 1. 最初のステップ 2. 2 番目のステップ 3. 3 番目のステップ ``` ### 引用 ```markdown > これは引用テキストです。 > 複数行にまたがることができます。 ``` ### 水平線 ```markdown --- ``` --- ## リンク ### 内部リンク 内部ドキュメントリンクはドキュメントスラッグを URL として使用： ```markdown 詳細は [CAN Bus Protocol](/docs/can-bus-protocol) を参照してください。 ``` ### 外部リンク ```markdown [Visit GitHub](https://github.com/example) ``` ### アンカーリンク ```markdown [インストールセクションにジャンプ](#installation-steps) ``` --- ## 画像とメディア ### 画像 `public/media/` ディレクトリ内の画像を相対パスで参照： ```markdown  ``` 画像の機能： - 自動レスポンシブスケーリング - 自動角丸 - alt テキストが自動的にキャプションとして表示 ### 動画埋め込み 拡張構文を使用して動画を埋め込み： ```markdown :::video[動画の説明](https://bilibili.com/video/BVxxx) ::: ``` サポートされているプラットフォーム： - Bilibili - YouTube - その他の標準動画 URL ### 3D モデル ```markdown :::model[モデル名](/media/model.step) ::: ``` ### ファイルダウンロード PDF、DOC、STEP などのファイルは自動的にダウンロードカードとしてレンダリング： ```markdown [ユーザーマニュアル](/media/manual.pdf) ``` --- ## コード ### インラインコード ```markdown `git clone` コマンドを使用してリポジトリをクローンします。 ``` ### コードブロック ````markdown ```bash # 依存関係のインストール npm install ``` ```python import os print("Hello, World!") ``` ```json { "name": "example", "version": "1.0.0" } ``` ```` サポートされている言語識別子：`bash`、`python`、`javascript`、`json`、`yaml`、`cpp`、`csharp`、`java`、`html`、`css` など。 ### 配線図アライメント コードブロック内で配線図を描く際は、左列を等幅で揃える必要があります： **正しい例（等幅アライメント）：** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN バス高 GND ———— システム地 ``` **アライメントルール：** - `————`（全角ダッシュ、各 2 セル）は各行で同じキャラクターカラムから開始すること - 各 ASCII 文字 = 1 セル、各 CJK 文字 = 2 セル - アライメントを簡単にするために ASCII ハイフン（`-------`）を推奨 --- ## テーブル ```markdown | カラム 1 | カラム 2 | カラム 3 | |----------|----------|----------| | セル 1 | セル 2 | セル 3 | | セル 4 | セル 5 | セル 6 | ``` --- ## コールアウトブロック（注意書き） GEO Wiki Pro は複数のコールアウトタイプをサポート： ```markdown ::: note 補足情報。 ::: ::: tip 有用なヒップとベストプラクティス。 ::: ::: warning 重要な注意事項。黄色のボーダーでレンダリング。 ::: ::: danger 重要な安全情報。赤いボーダーでレンダリング。 ::: ``` --- ## FAQ ブロック ```markdown ::: faq **Q: デバイスをリセットするには？** リセットボタンを 5 秒間長押ししてください。 **Q: 最大ケーブル長は？** 250 kbps の CAN バスで 30 メートル。 ::: ``` --- ## よくあるエラーと注意事項 ### 1. ファイルシステムを直接編集しない すべてのファイル書き込みは `saveDoc()` または `saveDb()` を通じて行う必要があります。`fs.writeFileSync` を直接使用しないでください。 ### 2. スラッグは変更不可 一度作成されると、スラッグはファイル名と URL として使用されます。スラッグの変更は新しいドキュメントを作成することと同じです。 ### 3. 共有フィールドの同期 `category`、`tags`、`author`、`sort` を更新すると、すべての言語バージョンに影響します。 ### 4. 画像パス 画像は `public/media/` ディレクトリに配置し、`/media/filename.ext` パスで参照する必要があります。 ### 5. エンコーディング規範 すべてのユーザーに表示されるテキストは `t()` 関数（i18n）を通過する必要があります。文字列をハードコードしないでください。 --- ## 執筆チェックリスト - [ ] YAML Frontmatter に必須フィールドがすべて含まれている - [ ] スラッグが命名規則に準拠（ASCII、特殊文字なし） - [ ] 見出し階層が正しい（`#` は 1 つ、`##`/`###` は複数） - [ ] コードブロックに正しい言語識別子が指定されている - [ ] 内部リンクが `/docs/slug` 形式を使用 - [ ] 画像が `/media/` 相対パスを使用 - [ ] テーブルフォーマットが正しい - [ ] 配線図がアライメントされている - [ ] 重要な情報にコールアウトブロックを使用 - [ ] 説明フィールドが簡潔で検索価値がある --- *最終更新: 2026-06-06 | バージョン: v3.0.2*