Obsidianのドキュメントは、このページに記載されているスタイルガイドラインに従っています。これらのガイドラインは、特に[Googleデベロッパードキュメントスタイルガイド](<https://developers.google.com/style>)および[Microsoftスタイルガイド](https://learn.microsoft.com/en-us/style-guide/)といった業界のベストプラクティスに基づいています。以下でカバーされていないエッジケースについては、二次的な参考資料としてこれらの外部ガイドを参照してください。 > [!tip]- 貢献する > ドキュメントの多くは、このスタイルガイドが作成される前から存在していました。 > > このスタイルガイドに違反している箇所を見つけた場合は、[issueを作成](https://github.com/obsidianmd/obsidian-docs/issues/new)し、[obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs)にプルリクエストを送信してください。 ## 用語と文法 ### 言語スタイル 英語ドキュメントにおいては、世界中のユーザーにより良くサービスを提供し、[[#翻訳]]を支援するために[グローバル英語](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html)を使用することが推奨されます。これは以下を意味します： - 慣用句や文化に特有の表現を避ける - 能動態と直接的な文構造を使用する - 複雑な専門用語よりも、シンプルで一般的な単語を優先する - 暗黙的ではなく明示的にする - スペルの慣例については、アメリカ英語を使用する（例：'organise'ではなく'organize'）。 ### 用語 - 「hotkey」よりも「keyboard shortcut」を優先する。ただし、特定の機能を参照する場合はHotkeyを使用する。 - モバイルでは「the Obsidian app」、デスクトップでは「the Obsidian application」を優先する。 - 「synchronise」や「synchronising」よりも「sync」や「syncing」を優先する。 - 「search query」よりも「search term」を優先する。 - セクションを導入するテキストを指す場合は、「header」よりも「heading」を優先する。 - 「max」よりも「maximum」、「min」よりも「minimum」を優先する。 ### プロダクト名 Obsidianのプロダクト名は「Obsidian」で始まります（例：「Obsidian Publish」、「Obsidian Sync」）。 段落が過度に繰り返しになる場合は、後続の参照で短縮形を使用できます。 例： _デバイス固有の設定を可能にするため、Obsidian Syncは自身の設定を同期しません。それぞれのデバイスでSyncを設定する必要があります。_ ### UIとインタラクション - ボタンテキストを示す場合は**太字**を使用する - 「tap」や「click」よりも「select」を優先する。 - モバイル固有の操作説明では、「click」が利用できないため、タッチ操作を説明する際に「tap」を使用しても問題ありません。 - 「side bar」よりも「sidebar」を優先する。 - コマンドやアクションを参照する場合、「invoke」や「execute」よりも「perform」を優先する。 一連のUI操作を参照する場合は、→（U+2192）記号を使用します。例：「**[[設定]] → コミュニティプラグイン**」。 ### ノート、ファイル、フォルダ - 保管庫内の Markdown ファイルを指す場合は「ノート」を使用する。 - Markdown 以外のファイル拡張子を指す場合は「ファイル」を使用する。 - 「ノートタイトル」よりも「ノート名」を優先する。 - 「現在のノート」よりも「アクティブなノート」を優先する。 - 「ディレクトリ」よりも「フォルダ」を優先する。 - 「ファイル形式」よりも「ファイルタイプ」を優先する。ただし、ファイル内容のデータ形式を具体的に指す場合は除きます。 ノート間を移動する場合、移動先が非表示の場合は「開く」を、ソースと移動先のノートが別々の分割画面で開かれている場合は「切り替える」を使用します。 ### 設定のリファレンスドキュメント 可能な場合、設定はすべてObsidian内で説明テキストを使用してドキュメント化すべきです。以下の場合を除き、Obsidianヘルプで特定の設定をドキュメント化することは避けてください： - 使用方法やタイミングについて、より深い知識が必要な場合。 - 一般的に誤用されたり、質問が多い場合。 - ユーザーエクスペリエンスを_大幅に_変更する場合。 特定の設定に注意を引きたい場合は、ヒントのコールアウトの使用を検討してください。 ### 方向を示す用語 方向を示す用語を形容詞として使用する場合はハイフンでつなぎます。方向が名詞として使用される場合はハイフンを使用しません。 **推奨：** - 左下隅の**[[設定]]**を選択します。 - 左下の**[[設定]]**を選択します。 **非推奨：** - 左下隅の**[[設定]]**を選択します。（ハイフンなし） - 左下の**[[設定]]**を選択します。（ハイフンあり） 「top-left」「top-right」よりも「upper-left」「upper-right」を優先します。 設定を参照する際に方向を示さないでください。設定コントロールの位置はデバイスによって異なります。 **推奨：** - **リモート保管庫を選択**の横にある**選択**を選びます。 **非推奨：** - **リモート保管庫を選択**の右側にある**選択**を選びます。 UI要素の垂直方向を説明する場合、空間的な関係には「上」と「下」を使用します。文脈によって曖昧になる「上へ」や「下へ」は避けてください。 **推奨：** - 検索ボックスはファイルリストの上に表示されます。 - 追加のオプションは下に表示されます。 **非推奨：** - 検索ボックスはファイルリストの上方にあります。 - さらにオプションがずっと下にあります。 ### 操作説明 ガイド名、セクション見出し、ステップバイステップの操作説明には命令形を使用します。命令形は簡潔でアクション指向であり、操作説明に従うユーザーにとってより分かりやすくなります。 - 「設定する」を「設定について」よりも優先する - 「ファイルを移動する」を「ファイルの移動について」よりも優先する - 「ノートをインポートする」を「ノートのインポートについて」よりも優先する ### センテンスケース 見出し、ボタン、タイトルには*タイトルケース*よりも*センテンスケース*を優先します。UI要素を参照する場合は、常にUI内のテキストの大文字小文字に合わせてください。 **推奨：** - How Obsidian stores data **非推奨：** - How Obsidian Stores Data ### 例 無意味な用語よりも現実的な例を優先します。 **推奨：** - `task:(call OR schedule)` **非推奨：** - `task:(foo OR bar)` ### キー名とキーボードショートカット キーボードのキーやショートカットを参照する場合は、一貫した表記を使用します。 **個々のキー名：** キーボード上の文字を名前で参照する場合は、名前の直後に括弧内に文字を追加します。 **推奨：** - ハイフン（-）キーを押してダッシュを追加します。 - クエスチョンマーク（?）を使用して検索します。 **非推奨：** - ハイフンキーを押してダッシュを追加します。 - ? を使用して検索します。 - 単語の前に `-` を追加します。 **キーボードショートカット：** キーボードショートカットはプラス記号の前後にスペースを入れずにフォーマットします。ショートカットがオペレーティングシステム間で異なる場合は、両方を指定します。 **推奨：** - `Ctrl+Z`（Windows）または`Command+Z`（macOS）を押して元に戻します。 - `Escape`を押してこのウィンドウを閉じます。 - `Tab`を使用してフィールド間を移動します。 **非推奨：** - `Cmd+Z`を押して元に戻します。 - `Ctrl + Z`（スペースあり）を押して元に戻します。 - `Ctrl/Cmd+Z`を押して元に戻します。 すべてのプラットフォームで同一のショートカットの場合、OSを指定する必要はありません。ショートカットがプラットフォームによって異なるか不明な場合は、安全のためにOSを指定してください。WindowsとLinuxは通常同じショートカットを使用します。 ### Markdown Markdown ブロック間には改行を入れます： **推奨：** ```md # 見出し 1 これはセクションです。 1. 最初の項目 2. 2番目の項目 3. 3番目の項目 ``` **非推奨：** ```md # 見出し 1 これはセクションです。 1. 最初の項目 2. 2番目の項目 3. 3番目の項目 ``` **箇条書きリストでのemダッシュ：** 太字の用語と説明を区切るために、箇条書きリストではemダッシュ（—）を使用します。リンクを含むシンプルなネストされた箇条書きリストではemダッシュを使用しないでください。 **推奨：** - **表示メニュー** — ビューの作成、編集、切り替え。 - **値を計算** — 価格の追加、合計の計算、数学的操作の実行。 **非推奨：** - [[ベースの作成]] — ベースの作成と埋め込み方法を学ぶ。 ### 画像 画像や画面の寸法を説明する際は「**幅** x **高さ** ピクセル」を使用します。 **例：** 推奨画像サイズ：1920 x 1080 ピクセル。 ## 情報構造 ### コールアウトの種類 特定の種類の情報を強調するために、コールアウトを戦略的に使用します： **ヒント**（`[!tip]-`）- ユーザーのワークフローを向上させる実用的なアドバイスやベストプラクティス。ショートカット、回避策、または必須ではないが有用な情報に使用します。これらのコールアウトは折りたたまれた状態で開始します。 **情報**（`[!info]+`）- 追加のコンテキスト、背景情報、または説明。理解を深めるが、タスクの完了には必須ではない情報に使用します。これらのコールアウトは展開された状態で開始します。 **警告**（`[!warning]+`）- データ損失、エラー、または意図しない結果を防ぐための重要な注意事項。本当にリスクのある状況に対して控えめに使用します。これらのコールアウトは決して折りたたんではいけません。 **例**（`[!example]-`）- 一般的な補足や追加の詳細。一部のユーザーにとって関連性がある可能性のある付随的な情報に使用します。これらのコールアウトは折りたたまれた状態で開始します。 **例：** ```md > [!tip]- キーボードショートカットを使う > よく使うショートカットを覚えることで、ワークフローを高速化できます。 > [!info]+ これは有料アドオンです > この機能を使用するには有料サブスクリプションが必要です。 > [!warning]+ この操作は元に戻せません > 保管庫の削除は永久的です。先にノートのエクスポートを検討してください。 > [!example]- 高度な使い方 > この設定はグラフメニューからも構成できます。 ``` ### リストと文章 離散的な項目で、強い順序的または因果関係を持たないものを提示する場合はリストを使用します。項目が互いに関連し、説明が必要な場合や、叙述的な流れから恩恵を受ける場合は文章と段落を使用します。 **リストを使用する場合：** - 無関係な機能のセット - インストール要件 - 設定オプション - トラブルシューティング手順 **文章を使用する場合：** - 何かの仕組みの説明 - 依存関係のあるワークフロー - 概念的な概要 - コンテキストが必要なガイダンス ### テーブル 機能、バージョン、または関連するデータポイントを比較する場合に、整列が理解を助けるところでテーブルを使用します。シンプルなリストや単一列のデータにはテーブルを使用しないでください。 **良い使用例：** | 機能 | モバイル | デスクトップ | |---------|--------|---------| | 同期 | はい | はい | | プラグイン | いいえ | はい | | テーマ | 制限あり | 完全 | ### 相互参照 ユーザーが関連トピックをナビゲートしやすいように、内部ウィキリンク（`[[ノート名]]`）を積極的に使用します。ただし、リンクの過剰使用は避けてください： - 同じページ内で同じ用語を複数回リンクしない - 参照先のページが大きな追加コンテキストを提供する場合にのみリンクする - 有用な場合は説明的なリンクテキストを使用する：`[[ノート名#セクション|説明的なテキスト]]` **例：** 初回の言及：「デバイス間で保管庫を最新の状態に保つには、[[Obsidian Syncの紹介|Obsidian Sync]]について学んでください。」 以降の言及：「各デバイスでSyncを個別に設定できます。」 ### プラットフォーム固有のコンテンツ プラットフォーム間で機能が異なる場合は、セクション見出しを使用してコンテンツを整理します。 プラットフォーム固有の操作説明や機能を区切るには、サブセクション見出しとして`デスクトップ`と`モバイル`を使用します。 **推奨：** ```md ## リボンのカスタマイズ ### デスクトップ デスクトップ版では、以下の方法でリボンをカスタマイズできます： - アイコンをドラッグ＆ドロップしてリボンアクションの順序を並べ替えます。 - 特定のアクションを非表示にするには、空白のスペースを右クリックして、非表示にしたいアクションのチェックを外します。 ### モバイル モバイル版では、設定を通じてリボンをカスタマイズできます： 1. **[[設定]]**を開きます。 2. **外観**に移動します。 3. **リボンの設定**の下にある**管理**をクリックします。 ``` > [!info]+ セクションを作成するタイミングは？ > コンテンツが大幅に異なる場合にのみ別々のセクションを作成してください。操作説明がほぼ同じで、わずかな違いしかない場合は、インラインの注記を使用してください。 ## アイコンと画像 言葉で説明するのが難しい事柄をより簡単に説明する場合や、Obsidianアプリケーションの重要な部分を表示する必要がある場合に、アイコンと画像を含めてください。画像は`Attachments`フォルダに保存できます。 - 画像は、付随するテキストをより理解しやすくするものであるべきです。 **例**：有効にすると、[[ワードカウント]]プラグインは下部のステータスバーに新しいエントリを作成します。 ![[Style-guide-zoomed-example.png#interface|300]] - 画像は`.png`または`.svg`形式であるべきです。 - ノート内で画像が大きすぎる場合は、Obsidianの外部で小さくするか、[[ファイルの埋め込み#ノートに画像を埋め込む|ノートに画像を埋め込む]]で説明されているように寸法を調整してください。 - まれに、特に大きいまたは複雑な画像を[[コールアウト#折りたたみ可能なコールアウト|折りたたみコールアウト]]内に配置したい場合があります。 - ポップアップウィンドウやモーダルの場合、画像はObsidianアプリケーションウィンドウ全体を表示するべきです。 ![[Style-guide-modal-example.png#interface]] ### アイコン [Lucide](https://lucide.dev/icons/)およびカスタムObsidianアイコンは、機能の視覚的な表現を提供するために詳細な要素と一緒に使用できます。 **例：** 左側のリボンメニューで、**新規キャンバスを作成**（ ![[lucide-layout-dashboard.svg#icon]] ）を選択して、アクティブなファイルと同じフォルダにCanvasを作成します。 **アイコンのガイドライン** - アイコンは`Attachments/icons`フォルダに保存します。 - Lucideアイコン名の前にプレフィックス`lucide-`を追加します。 - Obsidianアイコン名の前にプレフィックス`obsidian-icon-`を追加します。 **例：** 新規キャンバスを作成するアイコンは`lucide-layout-dashboard`と名付けるべきです。 - 利用可能なアイコンのSVGバージョンを使用します。 - アイコンの幅は`18`ピクセル、高さは`18`ピクセル、ストローク幅は`1.5`にしてください。これらの設定はSVGデータ内で調整できます。 > [!info]- SVGでのサイズとストロークの調整 > ```html > <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg> >``` - 埋め込み画像の`icon`アンカーを利用して、アイコン周囲のスペースを調整し、近くのテキストときれいに揃うようにします。 - アイコンは括弧で囲みます。（ ![[lucide-cog.svg#icon]] ） **例**：`![[lucide-cog.svg#icon]]` ### 画像アンカータグ 画像アンカータグは、埋め込み画像に装飾的な変更を追加するために利用できます。 > [!warning] ライブプレビューの警告 > アイコンアンカータグは**ライブプレビュー**では正しく表示されません。**リーディングビュー**を使用して、アンカータグが適用されていることを確認してください。 **アイコン** `![[lucide-menu.svg#icon]]` アイコンアンカータグは、インターフェース要素を示すために使用されるアイコンの正しい垂直方向の配置を保証します。 最初のメニューアイコンはアンカータグを使用しており（ ![[lucide-menu.svg#icon]] ）、2番目のメニューアイコン（ ![[lucide-menu.svg]] ）は使用していません。 **インターフェース** `![[Vault picker.png#interface]]` インターフェースアンカータグは、画像の周囲に装飾的なボックスシャドウを追加します。最初の画像にはインターフェースアンカータグが適用されています。 ![[Vault picker.png#interface]] 対照的に、2番目の画像にはインターフェースアンカーが適用されていません。 ![[Vault picker.png]] **アウトライン** `![[Backlinks.png#outline]]` アウトラインアンカータグは、画像の周囲に微妙なボーダーを追加します。最初の画像にはアウトラインアンカータグが適用されています。 > [!tip] 違いを確認するには、画像の左下部分に注目してください。 ![[Backlinks.png#outline]] 2番目の画像にはアウトラインアンカータグがありません。 ![[Backlinks.png]] ### 最適化 画像はページの読み込み時間を遅くし、貴重な[[Obsidian Publishの概要|Publish]]のストレージスペースを消費します。画像を最適化することで、画像の視覚的な品質を維持しながらファイルサイズを削減できます。 画像とアイコンの両方を最適化するべきです。 > [!info] 画像最適化ツール > 画像サイズを削減するための推奨プログラムをいくつか紹介します。 > - **Windows：** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/) > - **macOS：** [ImageOptim](https://imageoptim.com/) > - **Linux/Unix** [Trimage](https://trimage.org) > > 最適化率は65〜75%を推奨します。 ## レイアウト ### リンク切れ プルリクエストを送信する前に、作業中の翻訳のドキュメントにリンク切れがないか確認し、修正してください。リンク切れは時間の経過とともに自然に発生する可能性があるため、正確性を検証することでドキュメントの品質維持に役立ちます。 リンク切れは[[コミュニティプラグイン]]やIDEで利用可能なツールを使用して確認できます。 ### 説明 このドキュメントはGitHub上で編集され、[[Obsidian Publishの概要|Obsidian Publish]]を通じてオンラインでホストされています。これにはソーシャルカードやその他の[[SEO]]要素のための[[ソーシャルメディアリンクプレビュー#説明|説明]]が含まれます。 作業中のページに`description`[[プロパティ|プロパティ]]がない場合は、追加してください。説明は150文字以内で、ページの内容を客観的に要約するものにしてください。 **良い例**：Learn to create templates that capture and organize web page metadata automatically with Web Clipper. **改善の余地あり**：Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper. ### 方向 アプリ内でアクションを実行する方法の[[#操作説明]]を書いたり書き直したりする際は、モバイル版とデスクトップ版の両方の手順を必ず含めてください。 モバイルまたはデスクトップデバイスにアクセスできない場合は、プルリクエストの送信時にその旨をお知らせください。 ## 翻訳 翻訳を完了する際は、コンテンツ全体を翻訳してください。これには以下が含まれますが、これに限りません： - ノート名 - フォルダ名 - エイリアス - 添付ファイル名 - 代替リンクテキスト