PowerShell ドキュメントのスタイル ガイド
この記事では、コンテンツに固有のスタイル PowerShell-Docsします。 概要に関するページで説明されている情報を基に しています。
製品の用語
PowerShell にはいくつかのバリエーションがあります。
PowerShell - これが既定です。 PowerShell 7 以降は、真の PowerShell と見なします。
PowerShell Core - .NET Core 上に構築された PowerShell。 "コア" という 用語の 使用は、コアと区別する必要がある場合にWindows PowerShell。
Windows PowerShell - .NET Framework 上で構築される PowerShell です。 Windows PowerShell は Windows にのみ付属しており、完全な Framework が必要です。
一般に、ドキュメント内の "Windows PowerShell" への参照は PowerShell に変更できます。 "Windows PowerShell" は、特定 の動作Windows PowerShell する場合に使用する必要があります。
関連製品
- Visual Studio Code (VS Code) - Microsoft の無料のオープンソース エディターです。 最初に、完全な名前を使用する必要があります。 その後、次のコマンドを 使用VS Code。 "VSCode" を使用しない。
- PowerShell Extension for Visual Studio Code - この拡張機能は、VS Code PowerShell の優先 IDE に変換されます。 最初に、完全な名前を使用する必要があります。 その後、 PowerShell 拡張機能を使用できます。
- Azure PowerShell - これは、Azure サービスの管理に使用される PowerShell モジュールのコレクションです。
- Azure Stack PowerShell - これは、Microsoft のハイブリッド クラウド ソリューションを管理するために使用される PowerShell モジュールのコレクションです。
マークダウンの詳細
ドキュメントを作成する Microsoft Open Publishing System (OPS) では 、markdig を使用して Markdown ドキュメントを処理します。 Markdig は、最新の CommonMark 仕様の規則に基づいてドキュメント を解析 します。
新しい CommonMark 仕様は、一部の Markdown 要素の構築に関してはるかに厳密です。 このドキュメントで提供されている詳細に細心の注意を払います。
空白行、スペース、およびタブ
空白行は、Markdown 内のブロックの終わりも示します。 異なる種類の Markdown ブロックの間には、1 つの空白が必要です (たとえば、段落とリストまたはヘッダーの間)。
複数の連続する空白行は、HTML で単一の空白行としてレンダリングされます。 これらは目的を果たしません。 コード ブロック内では、連続する空白行によってコード ブロックが破損します。
行の末尾にある余分なスペースを削除します。
注意
Markdown では、スペースは重要です。 ハード タブではなくスペースを常に使用します。 末尾のスペースは、Markdown のレンダリング方法を変更できます。
タイトルと見出し
ATX 見出しだけを使用します (= または - スタイルのヘッダーではなく、# スタイル)。
- 文頭のみ大文字を使用する - 適切な名詞およびタイトルまたはヘッダーの最初の文字だけを大文字にする必要があります
#と見出しの最初の文字の間には、1 つのスペースが必要です- 見出しは 1 つの空白行で囲む必要があります
- ドキュメントあたり 1 つだけの H1
- ヘッダー レベルは 1 ずつインクリメントする必要があります。 レベルをスキップしない
- ヘッダーで太字または他のマークアップを使用しない
行の長さを 100 文字に制限します
これは、概念に関する記事とコマンドレットリファレンスに適用されます。 行の長さを制限すると、git の差分と履歴の読みやすさが向上します。 また、他のライターが投稿しやすくなっています。
指定された行の長さに合わせて段落Visual Studio Codeを簡単にリフローするには、 の Reflow Markdown 拡張機能を使用します。
About_topicsは 80 文字に制限されています。 詳細については、「ファイルの書式設定 」をAbout_してください。
表示内容
リストに複数の文または段落が含まれている場合は、リストではなくサブレベル ヘッダーの使用を検討してください。
リストは 1 つの空白行で囲む必要があります。
順序指定されていないリスト
複数の文が含まれている場合を限り、ピリオドでリスト項目を終了しない。 リスト項目の箇条書きには、ハイフン文字 (-) を使用します。 これにより、アスタリスク (*) を使用する、太字または斜体のマークアップとの混同を回避できます。 段落またはその他の要素を箇条書き項目の下に含めるには、改行を挿入し、インデントを行頭文字の後の最初の文字に揃えます。
次に例を示します。
This is a list that contain child elements under a bullet item.
- First bullet item
Sentence explaining the first bullet.
- Child bullet item
Sentence explaining the child bullet.
- Second bullet item
- Third bullet item
これは、箇条書き項目の下に子要素を含むリストです。
1 番目の箇条書き項目
1 番目の箇条書きを説明する文。
子箇条書き項目
子箇条書きを説明する文。
2 番目の箇条書き項目
3 番目の箇条書き項目
番号付きリスト
段落またはその他の要素を番号付き項目の下に含めるには、インデントを項目番号の後の最初の文字に揃えます。 番号付きリスト内のすべての項目では、各項目を 1. インクリメントするのではなく、数値を使用する必要があります。 Markdown のレンダリングでは、値が自動的にインクリメントされます。 これにより、項目の並べ替えが簡単になり、下位のコンテンツのインデントが標準化されます。
次に例を示します。
1. For the first element, insert a single space after the 1. Long sentences should be
wrapped to the next line and must line up with the first character after the numbered
list marker.
To include a second element (like this one), insert a line break after the first
and align indentations. The indentation of the second element must line up with
the first character after the numbered list marker. For single digit items, like
this one, you indent to column 4. For double digits items, for example item number
10, you indent to column 5.
1. The next numbered item starts here.
結果の Markdown は次のようにレンダリングされます。
1 番目の要素では、1 の後に 1 個のスペースを挿入します。 長い文は次の行に折り返す必要があり、番号付きリスト マーカーの後の最初の文字に揃えて配置する必要があります。
(この例のように) 2 つ目の要素を含めるには、1 つ目の要素の後に改行を挿入し、インデントを合わせます。 2 番目の要素のインデントは、番号付きリスト マーカーの後の最初の文字と揃える必要があります。 これのような 1 桁の項目では、列 4 にインデントします。 2 桁の項目の場合は (項目番号 10 など)、列 5 にインデントします。
次の番号付き項目はここから始まります。
イメージ
イメージをインクルードするための構文は次のようになります。
![[alt text]](<folderPath>)
Example:

alt text はイメージの簡単な説明であり、<folder path> はイメージの相対パスです。 目が不自由な人のためにスクリーン リーダー用の代替テキストが必要になります。
イメージは、記事を含む media/<article-name> フォルダー内のフォルダーに格納する必要があります。
記事間で画像を共有しない。 media フォルダーの下に、記事のファイル名と一致するフォルダーを作成します。 その記事のイメージをその新しいフォルダーにコピーします。 複数の記事でイメージが使用されている場合は、各イメージ フォルダーにそのイメージ ファイルのコピーを含める必要があります。 これにより、ある記事でイメージを変更しても、別の記事に影響を与えることがなくなります。
次のイメージ ファイルの種類がサポートされています: *.png、、*.gif``*.jpeg、、 *.jpg``*.svg
Open Publishing でサポートされる Markdown の拡張機能
Microsoft Docs 作成パックには 、発行システムに固有の機能をサポートするツールが含まれています。 アラートは、コンテンツの重要性を強調する色とアイコンを docs.microsoft.com にレンダリングするブロッククォートを作成する Markdown 拡張機能です。 次の種類のアラートがサポートされています。
> [!NOTE]
> Information the user should notice even if skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Essential information required for user success.
> [!CAUTION]
> Negative potential consequences of an action.
> [!WARNING]
> Dangerous certain consequences of an action.
これらのアラートは docs.microsoft.com 上で次のように表示されます。
注 ブロック
注意
Information the user should notice even if skimming.
ヒント ブロック
ヒント
Optional information to help a user be more successful.
重要なブロック
重要
Essential information required for user success.
注意ブロック
注意事項
Negative potential consequences of an action.
警告ブロック
警告
Dangerous certain consequences of an action. (ある行動で起こるいくつかの危険な結果。)
ハイパーリンク
ハイパーリンクでは、Markdown 構文 を使用する必要があります
[friendlyname](url-or-path)。 リンク参照 がサポートされています。発行システムでは、次の 3 種類のリンクがサポートされています。
- URL リンク
- ファイル リンク
- 相互参照リンク
サイトに関する他 docs.microsoft.com へのリンクは、サイト相対パスである必要があります
外部 Web サイトに対する URL はすべて、ターゲット サイトに対して有効でない限り HTTPS を使用する必要があります。
リンクには、表示名 (通常はリンクされた記事のタイトル) が必要です
下部にある [ 関連リンク] セクションのすべての項目にハイパーリンクが設定されている必要があります
ハイパーリンクの角かっこ内でバックティック、太字、その他のマークアップを使用しない。
ベア URL は、特定の URI を文書化するときに使用できます。 URI はバックティックで囲む必要があります。 次に例を示します。
By default, if you don't specify this parameter, the DMTF standard resource URI `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
サイト上の他のコンテンツへの docs.microsoft.com
サイトに関 する他の記事への URL docs.microsoft.com サイト相対パスである必要があります。 相対リンクを作成する最も簡単な方法は、ブラウザーから URL
https://docs.microsoft.com/en-usをコピーし、マークダウンに貼り付ける値から を削除する方法です。 Microsoft のプロパティの URL に locales を含め (URL から削除する/en-us) 必要があります。 不要なクエリ パラメーターを URL から削除します。 削除する必要がある例を次に示します。?view=powershell-5.1- 特定のバージョンの PowerShell にリンクするために使用されます?redirectedfrom=MSDN- 古い記事から新しい場所にリダイレクトされた場合に URL に追加されました
特定のバージョンのドキュメントにリンクする必要
&preserve-view=trueがある場合は、 パラメーターをクエリ文字列に追加する必要があります。 例:?view=powershell-5.1&preserve-view=trueファイル リンクは、 参照記事間、または概念的な記事間のリンクに使用されます。 特定のバージョンの PowerShell のリファレンス記事にリンクする必要がある場合は、URL リンクを使用する必要があります。
- ファイル リンクには、相対ファイル パスが含まれている (例:
../folder/file.md) - すべてのファイル パスでスラッシュ () 文字が
/使用されます
- ファイル リンクには、相対ファイル パスが含まれている (例:
相互参照リンクは 、公開システムでサポートされている特別な機能です。 概念記事の相互参照リンクを使用して、.NET API またはコマンドレット リファレンスにリンクできます。
.NET API リファレンスへのリンクについては、 中央共同作成者 ガイドのドキュメントのリンクを使用する方法に関するページを参照してください。
コマンドレット 参照へのリンクの形式は です
xref:<module-name>.<cmdlet-name>。 たとえば、Get-ContentMicrosoft.PowerShell.Management モジュールの コマンドレットにリンク します。[Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)
ディープ リンクは、URL リンクとファイル リンクの両方で許可されます。 ターゲット パスの末尾にアンカーを追加します。 次に例を示します。
[about_Splatting](about_Splatting.md#splatting-with-arrays)[custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)
詳細については、ドキュメントのリンク の使用に関するページを参照してください。
コマンド構文要素の書式設定
コマンドレットとパラメーターには常に完全な名前を使用します。 エイリアスを具体的に示す場合を限り、エイリアスを使用しないようにしてください。
プロパティ、パラメーター、オブジェクト、型名、クラス名、クラス メソッドは太字である必要 があります。
- プロパティとパラメーターの値は、バックティック () でラップする必要があります
`。 - 角かっこで囲まれたスタイルを使用して型を参照する場合は、バックティックを使用します。 例:
[System.Io.FileInfo]
- プロパティとパラメーターの値は、バックティック () でラップする必要があります
言語キーワード、コマンドレット名、関数、変数、ネイティブの EXEs、ファイル パス、インライン構文の例は、バックティック (
`) 文字でラップする必要があります。次に例を示します。
The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns the output to the `$files` variable. ```powershell $files = Get-ChildItem C:\Windows ```PowerShell のキーワードと演算子はすべて小文字にする必要があります
コマンドレット名とパラメーターに適切な (パスカル) 大文字と小文字を使用する
名前でパラメーターを参照する場合、名前は 太字 にする必要があります。 パラメーターをハイフン プレフィックスと共に使用する場合は、パラメーターをバッククォートで囲む必要があります。 次に例を示します。
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.外部コマンドの使用例を示す場合は、例をバッククォートで囲む必要があります。 常にネイティブ コマンドにファイル拡張子を含めます。 次に例を示します。
To start the spooler service on a remote computer named DC01, you type `sc.exe \\DC01 start spooler`.ファイル拡張子を含めて、PowerShell のコマンドの優先順位に従って正しいコマンドが実行されます。
概念説明の記事 (リファレンス コンテンツではなく) を記述する場合は、コマンドレット名の最初のインスタンスをコマンドレットのドキュメントにハイパーリンクする必要があります。 ハイパーリンクの角かっこ内でバックティック、太字、その他のマークアップを使用しない。
次に例を示します。
This [Write-Host](/powershell/module/Microsoft.PowerShell.Utility/Write-Host) cmdlet uses the **Object** parameter to ...詳細については、この記事の 「ハイパーリンク」 セクションを参照してください。
コード サンプルの Markdown
Markdown は、次の 2 つの異なるコード スタイルをサポートしています。
- コード スパン (インライン) - 1 つのバックティック () 文字で
`マークされます。 スタンドアロン ブロックとしてではなく、段落内で使用されます。 - コード ブロック - トリプル バックティック (
```) 文字列で囲まれた複数行ブロック。 コード ブロックには、バックティックの後に言語ラベルが付く場合があります。 言語ラベルを使用すると、コード ブロックの内容を構文で強調表示できます。
すべてのコード ブロックは、コード フェンス内に含めるようにします。 コード ブロックにはインデントを使用しない。 Markdown ではこのパターンを使用できますが、問題が発生する可能性があり、回避する必要があります。
コード ブロックは、トリプル バックティック () コード フェンスで囲まれた 1 行以上```のコードです。
コード フェンス マーカーは、コード サンプルの前後にある独自の行に配置する必要があります。 コード ブロックの先頭にあるマーカーには、省略可能な言語ラベルを含めることができます。 Microsoft の Open Publishing System (OPS) では、言語ラベルを使用して、構文の強調表示機能をサポートしています。
サポートされている言語タグの完全な一覧については、一元化された共同作成者ガイドの フェンス されたコード ブロックに関するページを参照してください。
また、OPS では、コード ブロックの内容をクリップボードにコピーする [コピー] ボタンも追加されます。 これにより、コード をスクリプトにすばやく貼り付け、コード サンプルをテストできます。 ただし、ドキュメント内のすべての例が、この方法で実行されるわけではありません。 一部のコード ブロックは、PowerShell の概念を簡単に示しています。
このドキュメントでは、次の 3 種類のコード ブロックが使用されています。
- 構文ブロック
- わかりやすい例
- 実行可能ファイルの例
構文コード ブロック
構文コード ブロックは、コマンドの構文構造を記述するために使用されます。 コード フェンスで言語タグを使用しない。 この例は、Get-Command コマンドレットのすべての使用できるパラメーターを示しています。
```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
[-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
[-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```
この例では、for ステートメントを汎用的な用語で説明します。
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
わかりやすい例
わかりやすい例は、PowerShell の概念を説明するために使用されます。 これらは、実行のためにクリップボードにコピーすることを意図したのではなく、 これらは、入力が簡単でわかりやすい単純な例で最も一般的に使用されます。 コード ブロックには、PowerShell プロンプトと出力例を含めできます。
PowerShell 比較演算子を示す簡単な例を次に示します。 このケースでは、閲覧者がこの例をコピーして実行することは想定していません。
```powershell
PS> 2 -eq 2
True
PS> 2 -eq 3
False
PS> 1,2,3 -eq 2
2
PS> "abc" -eq "abc"
True
PS> "abc" -eq "abc", "def"
False
PS> "abc", "def" -eq "abc"
abc
```
実行可能ファイルの例
複雑な例、またはコピーして実行することを目的とした例では、次のブロックスタイルのマークアップを使用する必要があります。
```powershell
<Your PowerShell code goes here>
```
PowerShell コマンドで表示される出力は、構文の強調表示を防ぐために 出力 コード ブロックで囲む必要があります。 次に例を示します。
```powershell
Get-Command -Module Microsoft.PowerShell.Security
```
```Output
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
```
出力 コード ラベルは、構文強調表示システムでサポートされている公式の "言語" ではありません。 ただし、OPS によって Web ページのコード ボックス フレームに "Output" ラベルが追加されるので、このラベルは便利です。 [出力] コード ボックスには、構文が強調表示されません。
コーディング スタイルの規則
コード サンプルでの行の継続を避ける
PowerShell コード例では、行連結文字 (`) を使用しないでください。 これらはわかりにくいため、行末に余分なスペースがあると問題が発生する可能性があります。
- PowerShell スプラッティングを使用して、複数のパラメーターを持つコマンドレットの行の長さを減らします。
- パイプ () 文字の後、始めかっこ ()、かっこ (
{``()、角かっこ (|) など、PowerShell の自然な折れ線の機会を活用します[。
例で PowerShell プロンプトを使用しないようにする
プロンプト文字列の使用は推奨されません。コマンド ラインの使用方法を示すシナリオに限定する必要があります。 これらの例のほとんどでは、プロンプト文字列は である必要があります PS>。 このプロンプトは OS 固有のインジケーターに依存しません。
プロンプトは、プロンプトを変更するコマンドや、表示されるパスがシナリオにとって重要な場合を示す例で必要です。 次の例は、レジストリ プロバイダーの使用時にプロンプトがどのように変化するかを示しています。
PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir
Hive: HKEY_CURRENT_USER\System
Name Property
---- --------
CurrentControlSet
GameConfigStore GameDVR_Enabled : 1
GameDVR_FSEBehaviorMode : 2
Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...}
Win32_GameModeRelatedProcesses : {1, 0, 1, 0...}
GameDVR_HonorUserFSEBehaviorMode : 0
GameDVR_DXGIHonorFSEWindowsCompatible : 0
例ではエイリアスを使用しない
エイリアスを具体的に文書化しない限り、すべてのコマンドレットとパラメーターの完全な名前を使用します。 コマンドレット名とパラメーター名では、適切な パスカルで大文字と小文字が区別される名前を使用する必要 があります。
例でのパラメーターの使用
位置指定パラメーターは使用しないでください。 一般に、パラメーターが位置指定の場合でも、常にパラメーター名を例に含める必要があります。 これにより、例で混乱を招く可能性が減ります。
コマンドレットリファレンスの書式設定に関する記事
コマンドレットのリファレンス記事には、特定の構造があります。 この構造は、PlatyPS によって定義されています。 PlatyPS は、Markdown で PowerShell モジュールのコマンドレット ヘルプを生成します。 マークダウン ファイルを編集した後、PlatyPS を使用して、Get-Help コマンドレットによって使用される MAML ヘルプ ファイルを作成します。
PlatyPS には、コード内に記述されるコマンドレット リファレンス用のハードコーディングされたスキーマが含まれます。 platyPS.schema.md ドキュメントでは、この構造が記述されています。 スキーマ違反があると、投稿を受け入れる前に修正する必要があるビルド エラーが発生します。
- ATX ヘッダー構造は削除されません。 PlatyPS では、特定のヘッダーのセットが想定されています。
- Input type ヘッダーと Output type ヘッダーでは、型が必要です。 コマンドレットが入力を受け取らない場合、または値を返す場合は、値 を使用します
None。 - インライン コード スパンは、どのパラグラフでも使用できます。
- フェンスされたコード ブロックは、 EXAMPLES セクションでのみ使用 できます。
PlatyPS スキーマでは、 EXAMPLES は H2 ヘッダーです。 各例は H3 ヘッダーです。 例では、スキーマでは、コード ブロックを段落で区切る必要はありません。 スキーマでは、次の構造が許可されます。
### Example X - Title sentence
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.
各例に番号を指定し、簡単なタイトルを追加します。
次に例を示します。
### Example 1: Get cmdlets, functions, and aliases
This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.
```powershell
Get-Command
```
### Example 2: Get commands in the current session
```powershell
Get-Command -ListImported
```
About_ ファイルの書式設定
About_* ファイルは Markdown で記述されますが、プレーンテキスト ファイルとして出荷されます。 Pandoc を使用して、Markdown をプレーン テキストに変換します。 About_* ファイルは、すべてのバージョンの PowerShell と発行ツールとの間で最適な互換性を確保するために書式設定されます。
基本的な書式設定に関するガイドライン:
通常行を 80 文字に制限する
コード ブロックは 76 文字に制限されます
ブロッククォート (およびアラート) は 78 文字に制限されます
これらの特殊なメタ文字 、、および を
\使用$する場合<:ヘッダー内では、先頭の文字
\を使用してこれらの文字をエスケープするか、バックティックを使用してコード スパンで囲む必要があります (`)段落内では、これらの文字をコード スパンに含む必要があります。 次に例を示します。
### The purpose of the \$foo variable The `$foo` variable is used to store ...
テーブルは 76 文字以内に収まる必要があります
複数行にまたがるセルの内容は手動で折り返します
各行で開始と終了の
|文字を使用します次の例は、セル内の複数の行をラップする情報を含むテーブルを適切に構築する方法を示しています。
``` |Operator|Description |Example | |--------|---------------------------|---------------------------------| |`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | | |is an instance of the |`True` | | |specified .NET type. | | |`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | | |not an instance of the |`False` | | |specified.NET type. | | |`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | | |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| ```注意
76 列の制限はトピックにのみ適用
About_*されます。 概念またはコマンドレットのリファレンス記事では、ワイド列を使用できます。
次のステップ
フィードバック
フィードバックの送信と表示