Docusaurusについて
Docusaurusでは、赤い枠の警告とかなんかそんなの作れないのかな
はい、Docusaurusでは、**「Admonitions (アドモニションズ)」**という機能を使って、赤い枠の警告や、青い枠の情報など、目立たせたいテキストブロックを簡単に作成できます。
Admonitionsの種類
Docusaurusには、以下のようないくつかの種類が用意されており、用途に応じて使い分けることができます。
| タイプ名 | 色 | 役割 |
|---|---|---|
note | 青 | 補足情報やヒント |
tip | 緑 | 便利なテクニックやコツ |
info | 青 | 重要な情報 |
warning | 黄 | 注意喚起 |
danger | 赤 | 警告や危険な情報 |
使い方
Markdownファイル内で、:::で囲むだけで簡単に作成できます。最初の:::の後に、タイプ名とタイトル（オプション）を記述します。
赤い枠の警告（danger）の例
:::danger
これは**非常に重要**な警告です。
この操作は元に戻せません。
:::
その他のアドモニションの例
:::note
これは補足情報です。
このセクションの概要を説明しています。
:::
:::tip
**ヒント:** `Ctrl + C`でプロセスを停止できます。
:::
:::warning
この機能は非推奨です。
:::
これは補足情報です。 このセクションの概要を説明しています。
ヒント: Ctrl + Cでプロセスを停止できます。
この機能は非推奨です。
これらのadmonitionは、Dキュメント内でユーザーに特に注意してほしい部分や、重要な情報を強調する際にとても便利です。
うーん、ソフトを紹介するときにあることになってるけど、実際は使えない場合は、noteかな？
いいえ、そのケースで最も適切で、よく使われるのは danger または warning です。
DocusaurusのAdmonitionsは、それぞれ異なる目的で使い分けられます。
-
note: 補足情報やヒントなど、必須ではないが役に立つ情報に使います。青い枠で表示され、ユーザーに注意を促すというよりは、情報を付け加えるニュアンスです。 -
danger: 破壊的な変更や、元に戻せない操作、システムに重大な影響を及ぼす可能性のある情報に使います。赤い枠で表示され、ユーザーに絶対に無視してはいけないという強い警告を伝えます。 -
warning:dangerほどではないが、注意を払うべき点や、非推奨の機能、将来的に変更される可能性のある情報に使います。黄色い枠で表示されます。
「ソフトを紹介するときにあることになってるけど、実際は使えない」という情報は、ユーザーの期待を裏切るものであり、作業の妨げになる可能性が高いため、**warningやdanger**を使って、明確に注意喚起することが適切です。
例えば、以下のように記述すると、ユーザーは一目でその情報が重要だと認識できます。
:::warning
この機能は、一部の環境では動作しません。
:::
この機能は、一部の環境では動作しません。
:::danger
注意: このツールは現在、利用できません。
:::
注意: このツールは現在、利用できません。
danger または warning どっちにする？
「ソフトを紹介するときにあることになってるけど、実際は使えない」という情報には、**warning**を使うのが適切です。
なぜなら、この情報はユーザーの作業を妨げる可能性があるものの、データが失われるような重大な危険性を伴うわけではないからです。dangerは、元に戻せない操作やシステムに深刻な影響を与えるような、より強い警告を伝えるために予約されています。
warningを使って、この機能が使えないという注意喚起を促すのが、最も適切で親切な方法です。
warningを使った例
:::warning
注意: この機能は、現在サポートされていません。
:::
注意: この機能は、現在サポートされていません。
dangerを使った例
:::danger
警告: この操作を実行すると、すべてのデータが削除されます。
:::
警告: この操作を実行すると、すべてのデータが削除されます。
このように、メッセージの内容に応じてAdmonitionを使い分けることで、ユーザーに情報の重要度を正確に伝えることができます。