This article provides style guidance specific to the PowerShell-Docs content. It builds on theinformation outlined in theOverview.

Formatting command syntax elements

Use the following rules to format elements of the PowerShell language when the elements are used ina sentence.

• Always use the full name for cmdlets and parameters in the proper Pascal case

• Only use an alias when you're specifically demonstrating the alias

• PowerShell keywords and operators should be all lowercase

• The following items should be formatted usingbold text:

  • Type names

  • Class names

  • Property names

  • Parameter names

    • By default, use the parameter without the hyphen prefix.
    • Use parameter name with the hyphen if you're illustrating syntax. Wrap the parameter inbackticks.

    For example:

    The parameter's name is **Name**, but it's typed as `-Name` when used on the commandline as a parameter.

• The following items should be formatted using backticks (`):

  • Property and parameter values

  • Type names that use the bracketed style - For example:[System.Io.FileInfo]

  • Referring to characters by name. For example: Use the asterisk character (*) to as a wildcard.

  • Language keywords and operators

  • Cmdlet, function, and script names

  • Command and parameter aliases

  • Method names - For example: TheToString() method returns a string representation of theobject

  • Variables

  • Native commands

  • File and directory paths

  • Inline command syntax examples - SeeMarkdown for code samples

    This example shows some backtick examples:

    The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assignsthe output to the `$files` variable.```powershell$files = Get-ChildItem C:\Windows```

    This example shows command syntax inline:

    To start the spooler service on a remote computer named DC01, you type:`sc.exe \\DC01 start spooler`.

    Including the file extension ensures that the correct command is executed according toPowerShell's command precedence.

Markdown for code samples

Markdown supports two different code styles:

• Code spans (inline) - marked by a single backtick (`) character. Used within a paragraphrather than as a standalone block.
• Code blocks - a multi-line block surrounded by triple-backtick (```) strings. Codeblocks can also have a language label following the backticks. The language label enables syntaxhighlighting for the contents of the code block.

All code blocks should be contained in a code fence. Never use indentation for code blocks. Markdownallows this pattern but it can be problematic and should be avoided.

A code block is one or more lines of code surrounded by a triple-backtick (```) code fence.The code fence markers must be on their own line before and after the code sample. The openingmarker can have an optional language label. The language label enables syntax highlighting on therendered webpage.

For a full list of supported language tags, seeFenced code blocks in the centralizedcontributor guide.

Publishing also adds aCopy button that can copy the contents of the code block to theclipboard. This allows you to paste the code into a script to test the code sample. However, not allexamples are intended to be run as written. Some code blocks are basic illustrations of PowerShellconcepts.

There are three types code blocks used in our documentation:

1. Syntax blocks
2. Illustrative examples
3. Executable examples

Syntax code blocks

Syntax code blocks are used to describe the syntactic structure of a command. Don't use a languagetag on the code fence. This example illustrates all the possible parameters of theGet-Commandcmdlet.

```Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]```

This example describes thefor statement in generalized terms:

```for (<init>; <condition>; <repeat>){<statement list>}```

Illustrative examples

Illustrative examples are used to explain a PowerShell concept. Yo`u shouldAvoid using PowerShell prompts in examples whenever possible. However, illustrative examplesaren't meant to be copied and pasted for execution. They're most commonly used for simple examplesthat are easy to understand. You may include the PowerShell prompt and example output.

Here's a simple example illustrating the PowerShell comparison operators. In this case, we don'tintend the reader to copy and run this example. Notice that this example usesPS> as a simplifiedprompt string.

```powershellPS> 2 -eq 2TruePS> 2 -eq 3FalsePS> 1,2,3 -eq 22PS> "abc" -eq "abc"TruePS> "abc" -eq "abc", "def"FalsePS> "abc", "def" -eq "abc"abc```

Executable examples

Complex examples, or examples that are intended to be copied and executed, should use the followingblock-style markup:

```powershell<Your PowerShell code goes here>```

The output displayed by PowerShell commands should be enclosed in anOutput code block toprevent syntax highlighting. For example:

```powershellGet-Command -Module Microsoft.PowerShell.Security``````OutputCommandType  Name                        Version    Source-----------  ----                        -------    ------Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.SecurityCmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security```

TheOutput code label isn't an officiallanguage supported by the syntax highlighting system.However, this label is useful because our publishing system adds theOutput label to the codebox frame on the web page. TheOutput code box has no syntax highlighting.

Coding style rules

Avoid line continuation in code samples

Avoid using line continuation characters (`) in PowerShell code examples. Backtick charactersare difficult to see and can cause problems if there are extra spaces at the end of the line.

• Use PowerShellsplatting to reduce line length for cmdlets that have several parameters.
• Take advantage of PowerShell's natural line break opportunities, like after pipe (|) characters,opening braces ({), parentheses ((), and brackets ([).

Avoid using PowerShell prompts in examples

Use of the prompt string is discouraged and should be limited to scenarios that are meant toillustrate command-line usage. For most of these examples, the prompt string should bePS>. Thisprompt is independent of OS-specific indicators.

Prompts are required in examples to illustrate commands that alter the prompt or when the pathdisplayed is significant to the scenario. The following example illustrates how the prompt changeswhen using the Registry provider.

PS C:\> cd HKCU:\System\PS HKCU:\System\> dir    Hive: HKEY_CURRENT_USER\SystemName                   Property----                   --------CurrentControlSetGameConfigStore        GameDVR_Enabled                       : 1                       GameDVR_FSEBehaviorMode               : 2                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}                       GameDVR_HonorUserFSEBehaviorMode      : 0                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Don't use aliases in examples

Use the full name of all cmdlets and parameters unless you're specifically documenting the alias.Cmdlet and parameter names must use the properPascal-cased names.

Using parameters in examples

Avoid using positional parameters. To reduce the chance of confusion, you should include theparameter name in an example, even if the parameter is positional.

Formatting cmdlet reference articles

Cmdlet reference articles have a specific structure.PlatyPS defines this structure. PlatyPSgenerates the cmdlet help for PowerShell modules in Markdown. After you edit the Markdown files,PlatyPS can create the MAML help files used by theGet-Help cmdlet.

PlatyPS has a schema that expects a specific structure for cmdlet reference. The PlatyPSschema document describes this structure. Schema violations cause build errors that must befixed before we can accept your contribution.

• Don't remove any of the ATX header structures. PlatyPS expects a specific set of headers in aspecific order.
• The H2INPUTS andOUTPUTS headers must have an H3 type. If the cmdlet doesn't take inputor return a value, then use the valueNone for the H3.
• Inline code spans can be used in any paragraph.
• Fenced code blocks are only allowed in theEXAMPLES section.

In the PlatyPS schema,EXAMPLES is an H2 header. Each example is an H3 header. Within anexample, the schema doesn't allow code blocks to be separated by paragraphs. The schema only allowsthe following structure:

### Example X - Title sentence0 or more paragraphs1 or more code blocks0 or more paragraphs.

Number each example and add a brief title.

For example:

### Example 1: Get cmdlets, functions, and aliasesThis command gets the PowerShell cmdlets, functions, and aliases that are installed on thecomputer.```powershellGet-Command```### Example 2: Get commands in the current session```powershellGet-Command -ListImported```

Formatting About_ files

About_* files are written in Markdown but are shipped as plain text files. We usePandoc toconvert the Markdown to plain text.About_* files are formatted for the best compatibility acrossall versions of PowerShell and with the publishing tools.

Basic formatting guidelines:

• Limit paragraph lines to 80 characters

• Limit code blocks to 76 characters

• Limit blockquotes and alerts to 78 characters

• When using these special meta-characters\,$, and<:

  • Within a header, these characters must be escaped using a leading\ character or enclosed incode spans using backticks (`)

  • Within a paragraph, these characters should be put into code spans. For example:

    ### The purpose of the \$foo variableThe `$foo` variable is used to store ...

• Markdown tables

  • ForAbout_* articles, tables must fit within 76 characters
    • If the content doesn't fit within 76 character limit, use bullet lists instead
  • Use opening and closing| characters on each line

Next steps

Editorial checklist