.NET ドキュメントのメタデータと Markdown テンプレート

  • [アーティクル]

この dotnet/docs テンプレートには、Markdown 構文の例とメタデータの設定方法が含まれています。

Markdown ファイルを作成するとき、付属のテンプレートを新しいファイルにコピーし、下のようにメタデータに入力し、上の H1 見出しを記事のタイトルに設定してください。

メタデータ

必須のメタデータ ブロックは次のサンプル メタデータ ブロックにあります。

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • コロン (:) とメタデータ要素の値の間にはスペースを入れる必要があります。
  • 値 (タイトルなど) 内のコロンによってメタデータ パーサーが中断されます。 その場合、タイトルを二重引用符で囲みます (例: title: "Writing .NET Core console apps: An advanced step-by-step guide")。
  • title: 検索エンジンの結果に表示されます。 タイトルは H1 見出しのタイトルと同じにしないでください。また、60 文字以下にする必要があります。
  • 説明: 記事の内容をまとめます。 通常、検索結果ページに表示されますが、検索ランキングには使用されません。 その長さはスペースを含めて 115-145 文字にする必要があります。
  • author: author フィールドには、作成者の GitHub ユーザー名を含める必要があります。
  • ms.date: 前回の大きな更新の日付です。 記事全体を見直し、更新している場合、既存の記事でこれを更新します。 誤植など、小さな修正の場合、更新されるとは限りません。

その他のメタデータは各記事に付け加えられますが、通常、ほとんどのメタデータ値は docfx.json に指定されているフォルダー レベルで適用されます。

基本的 Markdown、GFM、特殊文字

Markdown、GitHub Flavored Markdown (GFM)、OPS 固有の拡張機能の基本については、Markdown リファレンスの記事で学習できます。

Markdown では、書式設定に *、`、# のような特殊文字が使用されます。 このような文字をコンテンツに含める場合、次の 2 つのいずれかを行う必要があります。

  • 特殊文字の前にバックスラッシュを置いて "エスケープ処理" します (たとえば、* の場合 \*)。
  • その文字の HTML エンティティ コードを使用します (たとえば、* の場合 *)。

ファイル名

ファイル名では次の規則が使用されます。

  • 小文字、数字、ハイフンのみを含めることができます。
  • 空白や句読点は使用できません。 ファイル名の単語と数値はハイフンを使用して区切ります。
  • 動作を示す固有の動詞を使用します。develop、buy、build、troubleshoot などです。 進行形は使用しません。
  • スモール ワード (a、and、the、in、or など) を含めてはなりません。
  • Markdown フォーマットで、.md ファイル拡張子を使用する必要があります。
  • ファイル名は無理のない範囲で短くします。 ファイル名は記事の URL の一部になります。

見出し

文章スタイルで大文字と小文字を使い分けます。 見出しの最初の文字は必ず大文字にします。

テキストのスタイル設定

斜体
ファイル、フォルダー、パス (長い項目の場合、分割してそれだけの行にします)、新しい用語に使用します。

太字
UI 要素に使用します。

Code
インライン コード、言語キーワード、NuGet パッケージ名、コマンドライン コマンド、データベース テーブル、列名、クリック可能にしない URL に使用します。

アンカー、内部リンク、他のドキュメントのリンク、コード インクルード、外部リンクに関する詳細については、リンクに関する全般記事をご覧ください。

.NET ドキュメント チームでは次の規則に従っています。

  • ほとんどの場合、相対リンクを使用し、リンクに ~/ を使用することは奨励していません。相対リンクは GitHub のソースで解決されるためです。 ただし、依存レポジトリのファイルにリンクするときは必ず ~/ 文字を使用してパスを指定します。 依存レポジトリのファイルは GitHub の別の場所にあるため、記述方法に関係なく、相対リンクでは正しく解決されません。
  • C# 言語仕様と Visual Basic 言語仕様は、言語リポジトリからソースを含めることにより .NET ドキュメントに含められます。 Markdown ソースは csharplang リポジトリと vblang リポジトリで管理されます。

仕様のリンクは、その仕様が含まれるソース ディレクトリを指す必要があります。 以下の例にあるとおり、C# の場合は ~/_csharplang/spec であり、VB の場合は ~/_vblang/spec です。

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

このビルド システムには、外部リンクを使用しなくても .NET API にリンクできる拡張機能があります。 次のいずれかの構文を使用します。

  1. 自動リンク: <xref:UID> または <xref:UID?displayProperty=nameWithType>

    displayProperty クエリ パラメーターは、完全修飾のリンク テキストを生成します。 既定では、リンク テキストに表示されるのはメンバー名または型名のみです。

  2. マークダウン リンク: [link text](xref:UID)

    表示されるリンク テキストをカスタマイズする場合に使用します。

例:

  • <xref:System.String> は String としてレンダリングされます
  • <xref:System.String?displayProperty=nameWithType> は System.String としてレンダリングされます
  • [String class](xref:System.String) は String class としてレンダリングされます

この表記の使用について詳しくは、「Using cross reference」(相互参照の使用) を参照してください。

一部の UID には特殊文字 `、#、* が含まれています。UID の値は、それぞれ %60、%23、%2A のように HTML エンコードする必要があります。 かっこがエンコードされている場合もありますが、これは必須ではありません。

例:

  • System.Threading.Tasks.Task`1 は System.Threading.Tasks.Task%601 になります。
  • System.Exception.#ctor は System.Exception.%23ctor になります。
  • System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) は System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29 になります。

型の UID、メンバー オーバーロード、特定のオーバーロードされたメンバーを https://xref.learn.microsoft.com/autocomplete から見つけることができます。 クエリ文字列 ?text=*\<type-member-name>* では、UID を確認する型またはメンバーが特定されます。 たとえば、https://xref.learn.microsoft.com/autocomplete?text=string.format の場合、String.Format オーバーロードが取得されます。 このツールでは、指定された text クエリ パラメーターが UID のあらゆる部分で検索されます。 たとえば、メンバー名 (ToString)、部分的なメンバー名 (ToStri)、型とメンバーの名前 (Double.ToString) などを検索できます。

UID の後ろに * (または %2A) を追加すると、リンクは固有の API ではなく、オーバーロードのページを表すようになります。 これはたとえば、List<T>.BinarySearch(T, IComparer<T>) のような固有のオーバーロードではなく、List<T>.BinarySearch Method ページに汎用的な方法でリンクする必要がある場合に使用できます。 メンバーがオーバーロードされていない場合は、* を使用してメンバー ページにリンクすることもできます。このようにすると、UID にパラメーターの一覧を含める必要がなくなります。

特定のメソッド オーバーロードにリンクするには、メソッドの各パラメーターの完全修飾型名を含める必要があります。 たとえば、<xref:System.DateTime.ToString> はパラメーターなしの DateTime.ToString メソッドにリンクされますが、<xref:System.DateTime.ToString(System.String,System.IFormatProvider)> は DateTime.ToString(String,IFormatProvider) メソッドにリンクされます。

System.Collections.Generic.List<T> など、ジェネリック型にリンクするには、` (%60) 文字にジェネリック型パラメーターの番号を続けます。 たとえば、<xref:System.Nullable%601> は System.Nullable<T> 型にリンクされますが、<xref:System.Func%602> は System.Func<T,TResult> デリゲートにリンクされます。

コード

コードを含める最良の方法は、動作するサンプルからの抜粋を含めることです。 .NET に協力する方法に関する記事の指示に従い、サンプルを作成します。 完全なプログラムからのスニペットを含めることで、すべてのコードが Microsoft の継続的インテグレーション (CI) システムで実行されます。 ただし、コンパイル タイム エラーまたはランタイム エラーの原因を表示する必要がある場合、インライン コード ブロックを使用できます。

ドキュメントにコードを表示するための Markdown 構文の詳細については、「ドキュメントにコードを追加する方法」をご覧ください。

イメージ

静止画像またはアニメーション GIF

![this is the alt text](../images/Logo_DotNet.png)

リンク画像

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

ビデオ

YouTube ビデオは Markdown ファイルに埋め込むことができます。 動画の正しい URL を取得するには、動画を右クリックし、 [埋め込みコードのコピー] を選択し、<iframe> 要素から URL をコピーします。

> [!VIDEO <youtube_video_link>]

次に例を示します。

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft 拡張機能

learn.microsoft には、GitHub Flavored Markdownに関する追加の拡張機能がいくつか用意されています。

チェック済みリスト

カスタム スタイルはリストに使用できます。 緑のチェック マークを付けたリストをレンダリングできます。

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

これは次のようにレンダリングされます。

  • NET Core アプリの作成方法
  • Microsoft.XmlSerializer.Generator パッケージへの参照を追加する方法
  • MyApp.csproj を編集して依存関係を追加する方法
  • クラスと XmlSerializer を追加する方法
  • アプリケーションをビルドして実行する方法

.NET Core ドキュメントで、実際に使われているチェック済みリストの例を確認できます。

ボタン

ボタン リンク:

> [!div class="button"]
> [button links](dotnet-contribute.md)

これは次のようにレンダリングされます。

ボタン リンク

Visual Studio ドキュメントで、実際に使われているボタンの例を確認できます。

段階的手順

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

C# ガイドで、実際に使われている段階的手順の例を確認できます。