Skip to content

Latest commit

 

History

History
76 lines (55 loc) · 2.71 KB

6-UPDATING-REFERENCE.md

File metadata and controls

76 lines (55 loc) · 2.71 KB
Raw

Updating reference articles

The PowerShell documentation has

Cmdlet reference articles have a specific structure. This structure is defined by PlatyPS. PlatyPS is the tool we use to generate the cmdlet help for a PowerShell module and to create the MAML help files used by the Get-Help cmdlet.

PlatyPS has a hardcoded schema for cmdlet reference that is written into the code. The platyPS.schema.md document attempts to describe this structure. When updating cmdlet reference, if you don't follow this schema you can cause build errors that must be fixed before we can accept your contribution.

General guidelines

  • Do not remove any of the header structures. PlatyPS expect a specific set of headers.
  • The Input type and Output type headers must have a type. If the cmdlet does not take input or return a value then use the value "None".
  • Fenced code blocks are only allowed in the Examples section.
  • Inline code spans can be used in any paragraph.

Formatting About_ files

We are changing the way we process about_ files. About_* files are being reformatted for the best compatibility across PowerShell versions and our publishing tools. For details, see issue #1806. Please do not alter the formatting of about_ files without checking in with a repo maintainer.

Basic formatting guidelines:

  • Limit lines to 80 characters
  • Code blocks should be limited to 76 characters
  • Within a paragraph, the following characters must be escaped using a leading \ character: $, `, <
  • Tables need fit withing 76 characters
    • Manually wrap contents of cells across multiple lines
    • Use opening and closing | characters on each line
    • See a working example in about_Comparison_Operators

Writing examples

In the PlatyPS schema, the Examples header is an H2 header and each example is an H3 header.

The schema does not allow code blocks to be separated by paragraphs in an example. The valid schema is:

### Example #X title
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Number the examples and add a title for each example.

For example:

Example 1: Get cmdlets, functions, and aliases

Get-Command

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the computer.

Example 2: Get commands in the current session

Get-Command -ListImported