ドキュメントスタイルガイド
公式のスタイルガイドはまだありませんが、現在の OpenTelemetry ドキュメントのスタイルは以下のスタイルガイドに触発されています。
後述するセクションは、OpenTelemetry プロジェクト特有のガイドを含んでいます。
スタイルガイドの多くの要件は、自動化を実行することで強制できます。
プルリクエスト（PR）を提出する前に、ローカルマシンで npm run fix:all を実行して、変更をコミットしてください。
エラーまたは failed PR checks に遭遇した場合は、スタイルガイドを読み、特定の一般的な問題を修正するためにできることを学んでください。
OpenTelemetry.io ワードリスト
OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一貫して利用されるべきもの。
OpenTelemetry の用語と定義の完璧なリストには、用語集 を参照してください。
ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。
たとえば、“postgre” のかわりに “PostgreSQL” と表記してください。
すべてのリストは、.textlintrc.yml を確認してください。
Markdown
サイトページは、Goldmark Markdown レンダラーがサポートする Markdown 構文で書かれています。 サポートされている Markdown 拡張の完全な一覧は、Goldmark を参照してください。
次の Markdown 拡張も使用できます。
アラート
次の拡張構文を使用してアラートを書けます。
- GitHub-flavored Markdown（GFM）の alerts
- カスタムアラートタイトル用の Obsidian callout 構文
それぞれの例を以下に示します。
> [!TIP]
>
> 新しいコンテンツを書く場合は、通常、Docsy の
> [alert ショートコード](https://www.docsy.dev/docs/content/shortcodes/#alert) ではなく、
> この blockquote alert 構文を使うことを推奨します。
> [!WARNING] :warning: 空行が必要です！
>
> このサイトでは [Prettier] フォーマッターを使用しており、alert タグ/タイトルと
> alert 本文の間に空行が必要です。
これは次のようにレンダリングされます。
新しいコンテンツを書く場合は、通常、Docsy の alert ショートコード ではなく、 この blockquote alert 構文を使うことを推奨します。
このサイトでは Prettier フォーマッターを使用しており、alert タグ/タイトルと alert 本文の間に空行が必要です。
blockquote alert 構文の詳細は、Docsy ドキュメントの Alerts を参照してください。
リンク参照
Markdown の reference links を使用する場合は、shortcut 形式の [text] よりも、collapsed 形式の [text][] を推奨します。
どちらも有効な CommonMark ですが、shortcut 形式はすべての Markdown ツールで一貫して認識されるわけではありません。
特に、[example] と書いて定義を書き忘れた場合、markdownlint linter は警告しません1。
そのテキストはリンクではなく、リテラルの [example] として静かにレンダリングされます。
collapsed 形式の [example][] であれば、linter が定義の欠落を即座に検出します。
これは no-shortcut-ref-link カスタムルールによって強制されています。
shortcut reference を自動的に変換するには、npm run fix:markdown を実行してください。
Markdown チェック
Markdown ファイルの標準と一貫性を強制するため、すべてのファイルは markdownlint によって強制される特定のルールに従う必要があります。 すべてのルールの一覧は、.markdownlint.yaml と .markdownlint-cli2.yaml ファイルを確認してください。
ルールに対する正当な例外がある場合は、markdownlint-disable ディレクティブを使用してルールの警告を抑制してください。
詳細は