本文提供特定于 PowerShell-Docs 内容的样式指南。 它基于 概述中概述的信息。
命令语法元素的格式化
在句子中使用元素时，使用以下规则设置 PowerShell 语言元素的格式。
在 Pascal 大小写格式中，请始终使用 cmdlet 和参数的完整名称。
仅当你专门演示别名时使用别名
PowerShell 关键字和运算符应全部小写
应使用 粗体 文本设置以下项的格式：
类型名称
类名
属性名称
参数名称
- 默认情况下，使用不带连字符前缀的参数。
- 如果要说明语法，请使用带连字符的参数名称。 使用反引号将参数引起来。
例如：
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.
应使用反引号格式化以下项目（
`）：属性和参数值
使用括号样式的类型名称 - 例如：
[System.Io.FileInfo]用名字称呼角色。 例如：使用星号字符 （
*） 作为通配符。语言关键字和运算符
Cmdlet、函数和脚本名称
命令和参数别名
方法名称 - 例如：该方法
ToString()返回对象的字符串表示形式变量
本机命令
文件和目录路径
内联命令语法示例 - 有关代码示例，请参阅 Markdown
此示例显示了一些反杆示例：
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 ```此示例显示内联命令语法：
To start the spooler service on a remote computer named DC01, you type: `sc.exe \\DC01 start spooler`.包括文件扩展名可确保根据 PowerShell 的命令优先级执行正确的命令。
用于代码示例的Markdown
Markdown 支持两种不同的代码样式：
-
代码区段（内联） - 用单个反引号（
`）字符标记。 在段落中使用，而不是作为独立块使用。 -
代码块 - 由三个反引号（
```）字符串包围的多行块。 代码块中可以在反引号后加上语言标签。 语言标签使代码块内容能够进行语法高亮显示。
所有代码块都应包含在代码围栏中。 切勿对代码块使用缩进。 Markdown 允许此模式，但它可能是有问题的，应避免。
代码块是一行或多行代码，用三重反引号（```）代码框包围。
代码围栏标记必须在代码示例的前后各自占据一行。 打开标记可以具有可选的语言标签。 语言标签启用已渲染网页上的语法高亮显示。
有关支持的语言标记的完整列表，请参阅集中参与者指南中的 隔离代码块 。
发布还会添加“ 复制” 按钮，该按钮可将代码块的内容复制到剪贴板。 这样，就可以将代码粘贴到脚本中以测试代码示例。 但是，并非所有示例都旨在按写入方式运行。 某些代码块是 PowerShell 概念的基本插图。
文档中使用了三种类型代码块：
- 语法块
- 说明示例
- 可执行示例
语法结构代码块
语法代码块用于描述命令的语法结构。 不要在代码围栏上使用语言标记。 此示例演示了所有可能参数的 Get-Command cmdlet。
```
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 概念。 Yo'u 应 尽可能避免在示例中使用 PowerShell 提示 。 但是，说明性示例不应复制并粘贴以供执行。 它们最常用于易于理解的简单示例。 可以包括 PowerShell 提示符和示例输出。
下面是演示 PowerShell 比较运算符的简单示例。 在这种情况下，我们不希望读取器复制并运行此示例。 请注意，此示例用作 PS> 简化的提示字符串。
```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
```
Output 代码标签不是语法高亮系统支持的官方 语言。
但是，此标签非常有用，因为我们的发布系统将 输出 标签添加到网页中的代码框框架。
输出代码框没有语法突出显示。
编码样式规则
避免代码示例中的代码换行
避免在 PowerShell 代码示例中使用行延续字符（`）。 反引号字符很难看到，如果行末尾有额外的空格，可能会导致问题。
- 使用 PowerShell 喷洒 来减少具有多个参数的 cmdlet 的行长度。
- 利用 PowerShell 的自然换行机会，例如管道（
|）字符之后、左括号（{）、圆括号（(）和方括号（[）。
避免在示例中使用 PowerShell 提示
不建议使用提示字符串，应仅限于旨在说明命令行用法的方案。 对于其中大多数示例，提示字符串应为 PS>。 此提示独立于操作系统特定的指示器。
示例中需要提示来说明更改提示的命令，或者当显示的路径对方案很重要时。 以下示例说明在使用注册表提供程序时，提示如何发生变化。
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
不要在示例中使用别名
除非您专门记录别名，否则请使用所有 cmdlet 和参数的完整名称。 Cmdlet 和参数名称必须使用正确的 Pascal 格式 名称。
在示例中使用参数
避免使用位置参数。 若要减少混淆的可能性，应将参数名称包含在示例中，即使参数是位置。
设置 cmdlet 参考文章的格式
Cmdlet 参考文章具有特定的结构。
PlatyPS 定义此结构。 PlatyPS 生成 Markdown 格式的 PowerShell 模块命令帮助文档。 编辑完 Markdown 文件后，PlatyPS 可以创建由 cmdlet 使用的 MAML 帮助文件 Get-Help。
PlatyPS 的架构中，命令引用有一个特定的结构要求。 PlatyPS 架构文档 描述了此结构。 架构冲突会导致必须修复的生成错误，然后才能接受你的贡献。
- 请勿删除任何 ATX 标头结构。 PlatyPS 需要一组按照特定顺序排列的特定标头。
- H2 INPUTS 和 OUTPUTS 标头必须具有 H3 类型。 如果 cmdlet 不接受输入或不返回值，则 H3 应使用值
None。 - 内联代码片段可以用于任何段落。
- “ 示例 ”部分仅允许隔离代码块。
在 PlatyPS 架构中， 示例 是 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 ...
Markdown 表格
- 对于
About_*文章，表格必须限制在 76 个字符以内- 如果内容不符合 76 个字符的限制，请改用项目符号列表
- 在每个行上使用开始和结束
|字符
- 对于
