编辑 Markdown 帮助文件

PlatyPS 创建具有特定结构的 Markdown 模板文件。 维护此结构非常重要，以便 PlatyPS 可以正确更新内容并将其转换为其他格式。 该结构由一系列由 H1、H2 和 H3 接头定义的部分组成。 每个部分都有特定的目的和格式要求。 编辑文件时，需要确保遵循这些要求，不要更改部分的顺序，不要删除所需的部分，也不要添加新部分。

Markdown 文件结构

PlatyPS 生成的每个 Markdown 文件都有以下结构：

---
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

所有部分都是必填项，除非注明为可选。 必须保持各部分的顺序。 H2 标头必须为大写。

部分详情

以下内容介绍了文件每个部分的 Markdown 命令帮助格式要求。

YAML 前页

文件顶部的 YAML frontmatter 部分包含有关 cmdlet 的元数据。 frontmatter 由包含三个连字符 （）--- 的行分隔。 以下示例显示了 PlatyPS 自动生成的 YAML frontmatter。

---
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
---

下表描述了所需的元数据属性。

这是所需的最低元数据。 您可以根据需要添加其他元数据。 例如，用于创建网站的发布系统可能需要其他元数据。

H1 标题

H1 标题必须与 cmdlet 名称完全匹配。 示例：

# Get-Widget

H2 剧情简介

概要部分包含 cmdlet 的简要说明。 将描述限制为单个句子，最好是单行。

示例：

## SYNOPSIS

Gets one or more widgets based on specified criteria.

H2 语法

“语法”部分包含为 cmdlet 定义的每个参数集的语法图。 语法图应与命令提供 Get-Command -Syntax 的信息匹配。 如果命令具有多个参数集，则每个参数集都包含在单独的 H3 部分中。 H3 部分的标题是参数集的名称。

示例：

## SYNTAX

### DefaultParameterSet

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

## DetailedParameterSet

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

H2 别名

ALIASES 部分用于记录为 cmdlet 定义的别名。 如果没有别名，您可以删除此部分。 这是文件中唯一的可选部分。

示例：

## ALIASES

This cmdlet has the following aliases:

- `gwi`

H2 描述

DESCRIPTION 部分包含 cmdlet 的详细说明。 描述可以是多个段落长，并且应提供足够的信息，以便用户理解命令的用途。 避免提供太多细节。 您可以在 EXAMPLES、PARAMETERS 和 NOTES 部分提供更多详细信息。

H2 示例

EXAMPLES 部分包含一个或多个演示如何使用 cmdlet 的示例。 至少应该有一个例子。 每个示例都包含在 H3 部分中。 H3 部分的标题应简要描述示例的上下文。 与之前版本的 PlatyPS 不同，本节的内容没有限制。 您可以混合使用多个代码块和文本。 这使您可以提供示例和输出的更详细说明，包括需要多个代码块和单独说明的示例。

示例：

## EXAMPLES

### Example 1 - Get a widget by name

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

H2参数

PARAMETERS 部分包含为 cmdlet 定义的参数的说明。 如果命令不采用任何参数，则该部分可以为空，但需要 H2 标头。 每个参数都记录在自己的 H3 部分中。 H3 部分的标题是参数的名称。

示例：

### -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 会自动生成一个 YAML 代码块，其中包含有关参数的元数据。 您必须提供参数的描述。 除了少数特定字段外，不应更改 YAML 代码块的内容。 这些字段的这些值由 PlatyPS 通过使用反射检查 cmdlet 来填充。 可能需要更改的唯一例外情况是：

• DefaultValue - 默认值无法通过反射发现。
• SupportsWildcards - 仅当命令作者将属性应用于 [SupportsWildcards()] 参数时，此值才可发现。 不幸的是，即使支持通配符，此属性也不常用。

H2 输入

INPUTS 部分描述了 cmdlet 通过管道输入接受的类型对象。 每种类型都记录在自己的 H3 部分中。 H3 部分的标题是类型的名称。 使用完整类型名称。 H3 部分的内容应标识接受该类型输入的参数的名称。 如果 cmdlet 不接受管道输入，则该部分可以为空，但需要 H2 标头。

示例：

## INPUTS

### System.String

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

H2 输出

OUTPUTS 部分描述了 cmdlet 返回的对象类型。 每种类型都记录在自己的 H3 部分中。 H3 部分的标题是类型的名称。 使用完整类型名称。 H3 部分的内容应描述类型和任何重要属性。 如果 cmdlet 未返回任何对象，则该部分可以为空，但需要 H2 标头。

示例：

## OUTPUTS

### Widget

Outputs Widget objects representing the retrieved widgets.

H2 笔记

NOTES 部分包含有关 cmdlet 的其他信息。 该部分可以为空，但需要 H2 标头。 您可以使用此部分来记录特殊注意事项、限制、版本差异以及不适合其他部分的信息。

H2 相关链接

“相关链接”部分包含指向相关主题的链接。 该部分可以为空，但需要 H2 标头。 链接的格式应为 Markdown 链接的项目符号列表。 本节不应包含任何其他内容。

## RELATED LINKS

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

后续步骤

• 测试 Markdown 帮助文件