Edit Markdown help files

PlatyPS creates Markdown template files that have a specific structure. It's important to maintain this structure so that PlatyPS can correctly update and convert the content to other formats. The structure consists of a series of sections defined by H1, H2, and H3 headers. Each section has a specific purpose and format requirements. As you edit the files, you need to ensure that you follow these requirements, don't change the order of the sections, don't remove required sections, and don't add new sections.

Markdown file structure

Each Markdown file generated by PlatyPS has the following structure:

---
YAML metadata
---
H1: Cmdlet name
H2: SYNOPSIS
H2: SYNTAX
H2: ALIASES - optional header that can be removed if there are no aliases
H2: DESCRIPTION
H2: EXAMPLES
H3: Example title - at least one example is required
H2: PARAMETERS
H3: -ParameterName - zero or more parameters
H2: INPUTS
H3: TypeName - zero or more input types
H2: OUTPUTS
H3: TypeName - zero or more output types
H2: NOTES - Header required but section can be empty
H2: RELATED LINKS - Header required but section can be empty

All sections are required except where noted as optional. The order of the sections must be maintained. The H2 headers must be in uppercase.

Section details

The following content describes the Markdown command help format requirements for each section of the file.

YAML frontmatter

The YAML frontmatter section at the top of the file contains metadata about the cmdlet. The frontmatter is delimited by lines that contain three hyphens (---). The following example shows the YAML frontmatter automatically generated by PlatyPS.

---
document type: cmdlet
external help file: WidgetModule-Help.xml
HelpUri: ''
Locale: en-US
Module Name: WidgetModule
ms.date: 10/09/2025
PlatyPS schema version: 2024-05-01
title: Get-Widget
---

The following table describes the required metadata properties.

This is this minimum required metadata. You can add additional metadata as needed. For example, the publishing system you use to create a website might require additional metadata.

H1 title

The H1 title must match the cmdlet name exactly. Example:

# Get-Widget

H2 SYNOPSIS

The SYNOPSIS section contains a brief description of the cmdlet. Limit the description to a single sentence, preferably on a single line.

Example:

## SYNOPSIS

Gets one or more widgets based on specified criteria.

H2 SYNTAX

The SYNTAX section contains the syntax diagram for each parameter set defined for the cmdlet. The syntax diagrams should match the information provided by the Get-Command -Syntax command. If the command has multiple parameter sets, each parameter set is contained in a separate H3 section. The title of the H3 section is the name of the parameter set.

Example:

## SYNTAX

### DefaultParameterSet

```
Get-Widget [-Name] <string> [-Color <ConsoleColor>] [-Size <int>] [<CommonParameters>]
```

## DetailedParameterSet

```
Get-Widget [-Name] <string> [-Color <ConsoleColor>] [-Size <int>] [-Detailed] [<CommonParameters>]
```

H2 ALIASES

The ALIASES section is used to document aliases defined for the cmdlet. If there are no aliases, you can remove this section. This is the only optional section in the file.

Example:

## ALIASES

This cmdlet has the following aliases:

- `gwi`

H2 DESCRIPTION

The DESCRIPTION section contains a detailed description of the cmdlet. The description can be multiple paragraphs long and should provide enough information for the user to understand the purpose of the command. Avoid providing too much detail. You can provide more detail in the EXAMPLES, PARAMETERS, and NOTES sections.

H2 EXAMPLES

The EXAMPLES section contains one or more examples that demonstrate how to use the cmdlet. There should be at least one example. Each example is contained in an H3 section. The title of the H3 section should briefly describe the context of the example. Unlike the previous version of PlatyPS, there are no restrictions on the content in this section. You can mix multiple code blocks and text. This allows you to provide more detailed explanations of the examples and outputs, including examples that require multiple code blocks with separate explanations.

Example:

## EXAMPLES

### Example 1 - Get a widget by name

```powershell
Get-Widget -Name "Widget1"
```

H2 PARAMETERS

The PARAMETERS section contains descriptions of the parameters defined for the cmdlet. If the command takes no parameters, the section can be empty, but the H2 header is required. Each parameter is documented in its own H3 section. The title of the H3 section is the name of the parameter.

Example:

### -Color

Filter the results by the color of the widget.

```yaml
Type: System.ConsoleColor
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''
```

PlatyPS automatically generates a YAML code block that contains metadata about the parameter. You must provide a description of the parameter. Except for a few specific fields, you shouldn't change the content of the YAML code block. These values of these fields are populated by PlatyPS by inspecting the cmdlet using reflection. The only exceptions that might need to be changed are:

• DefaultValue - The default value is not discoverable by reflection.
• SupportsWildcards - This value is only discoverable if the command author applied the [SupportsWildcards()] attribute to the parameter. Unfortunately, this attribute is not commonly used, even when wildcards are supported.

H2 INPUTS

The INPUTS section describes the types objects that the cmdlet accepts via pipeline input. Each type is documented in its own H3 section. The title of the H3 section is the name of the type. Use full type names. The content of the H3 section should identify the name of the parameters that accepts that type of input. If the cmdlet doesn't accept pipeline input, the section can be empty, but the H2 header is required.

Example:

## INPUTS

### System.String

This cmdlet accepts pipeline input for the name of the widget.

H2 OUTPUTS

The OUTPUTS section describes the types of objects that the cmdlet returns. Each type is documented in its own H3 section. The title of the H3 section is the name of the type. Use full type names. The content of the H3 section should describe the type and any important properties. If the cmdlet doesn't return any objects, the section can be empty, but the H2 header is required.

Example:

## OUTPUTS

### Widget

Outputs Widget objects representing the retrieved widgets.

H2 NOTES

The NOTES section contains additional information about the cmdlet. The section can be empty, but the H2 header is required. You can use this section to document special considerations, limitations, version differences, and information that doesn't fit in other sections.

H2 RELATED LINKS

The RELATED LINKS section contains links to related topics. The section can be empty, but the H2 header is required. The links should be formatted as a bulleted list of Markdown links. This section should not contain any other content.

## RELATED LINKS

- [All about widgets](https://docs.tailspintoys.com/widgets)

Next steps

• Test the Markdown help files