Editar arquivos de ajuda de Markdown

PlatyPS cria arquivos de modelo Markdown que têm uma estrutura específica. É importante manter essa estrutura para que o PlatyPS possa atualizar e converter corretamente o conteúdo para outros formatos. A estrutura consiste em uma série de seções definidas por cabeçalhos H1, H2 e H3. Cada secção tem uma finalidade específica e requisitos de formato. Ao editar os arquivos, você precisa garantir que segue esses requisitos, não altere a ordem das seções, não remova as seções necessárias e não adicione novas seções.

Estrutura do arquivo Markdown

Cada arquivo Markdown gerado pelo PlatyPS tem a seguinte estrutura:

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

Todas as seções são obrigatórias, exceto quando indicado como opcional. A ordem das secções deve ser mantida. Os cabeçalhos H2 devem estar em maiúsculas.

Detalhes da secção

O conteúdo a seguir descreve os requisitos de formato de ajuda do comando Markdown para cada seção do arquivo.

Matéria frontal do YAML

A seção YAML frontmatter na parte superior do arquivo contém metadados sobre o cmdlet. A frente é delimitada por linhas que contêm três hífenes (---). O exemplo a seguir mostra o frontmatter YAML gerado automaticamente pelo 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
---

A tabela a seguir descreve as propriedades de metadados necessárias.

Trata-se dos metadados mínimos necessários. Você pode adicionar metadados adicionais conforme necessário. Por exemplo, o sistema de publicação que você usa para criar um site pode exigir metadados adicionais.

Título H1

O título H1 deve corresponder exatamente ao nome do cmdlet. Exemplo:

# Get-Widget

H2 SINOPSE

A seção SYNOPSIS contém uma breve descrição do cmdlet. Limite a descrição a uma única frase, de preferência numa única linha.

Exemplo:

## SYNOPSIS

Gets one or more widgets based on specified criteria.

SINTAXE H2

A seção SYNTAX contém o diagrama de sintaxe para cada conjunto de parâmetros definido para o cmdlet. Os diagramas de sintaxe devem corresponder às informações fornecidas pelo Get-Command -Syntax comando. Se o comando tiver vários conjuntos de parâmetros, cada conjunto de parâmetros estará contido em uma seção H3 separada. O título da seção H3 é o nome do conjunto de parâmetros.

Exemplo:

## SYNTAX

### DefaultParameterSet

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

## DetailedParameterSet

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

H2 ALIASES

A seção ALIASES é usada para documentar aliases definidos para o cmdlet. Se não houver aliases, você poderá remover esta seção. Esta é a única seção opcional no arquivo.

Exemplo:

## ALIASES

This cmdlet has the following aliases:

- `gwi`

H2 DESCRIÇÃO

A seção DESCRIPTION contém uma descrição detalhada do cmdlet. A descrição pode ter vários parágrafos e deve fornecer informações suficientes para que o usuário entenda a finalidade do comando. Evite fornecer muitos detalhes. Você pode fornecer mais detalhes nas seções EXEMPLOS, PARÂMETROS e NOTAS.

EXEMPLOS H2

A seção EXEMPLOS contém um ou mais exemplos que demonstram como usar o cmdlet. Deveria haver pelo menos um exemplo. Cada exemplo está contido em uma seção H3. O título da secção H3 deve descrever brevemente o contexto do exemplo. Ao contrário da versão anterior do PlatyPS, não há restrições sobre o conteúdo nesta seção. Você pode misturar vários blocos de código e texto. Isso permite que você forneça explicações mais detalhadas dos exemplos e saídas, incluindo exemplos que exigem vários blocos de código com explicações separadas.

Exemplo:

## EXAMPLES

### Example 1 - Get a widget by name

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

PARÂMETROS H2

A seção PARAMETERS contém descrições dos parâmetros definidos para o cmdlet. Se o comando não usar parâmetros, a seção pode estar vazia, mas o cabeçalho H2 é necessário. Cada parâmetro é documentado em sua própria seção H3. O título da seção H3 é o nome do parâmetro.

Exemplo:

### -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 gera automaticamente um bloco de código YAML que contém metadados sobre o parâmetro. Você deve fornecer uma descrição do parâmetro. Exceto por alguns campos específicos, você não deve alterar o conteúdo do bloco de código YAML. Esses valores desses campos são preenchidos pelo PlatyPS inspecionando o cmdlet usando reflexão. As únicas exceções que podem precisar ser alteradas são:

• DefaultValue - O valor padrão não é detetável por reflexão.
• SupportsWildcards - Este valor só é detetável se o autor do comando aplicou o [SupportsWildcards()] atributo ao parâmetro. Infelizmente, esse atributo não é comumente usado, mesmo quando há suporte para curingas.

H2 ENTRADAS

A seção INPUTS descreve os tipos de objetos que o cmdlet aceita por meio da entrada de pipeline. Cada tipo é documentado em sua própria seção H3. O título da seção H3 é o nome do tipo. Use nomes de tipo completos. O conteúdo da seção H3 deve identificar o nome dos parâmetros que aceitam esse tipo de entrada. Se o cmdlet não aceitar a entrada do pipeline, a seção poderá estar vazia, mas o cabeçalho H2 será necessário.

Exemplo:

## INPUTS

### System.String

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

SAÍDAS H2

A seção OUTPUTS descreve os tipos de objetos que o cmdlet retorna. Cada tipo é documentado em sua própria seção H3. O título da seção H3 é o nome do tipo. Use nomes de tipo completos. O conteúdo da secção H3 deve descrever o tipo e quaisquer propriedades importantes. Se o cmdlet não retornar nenhum objeto, a seção poderá estar vazia, mas o cabeçalho H2 será necessário.

Exemplo:

## OUTPUTS

### Widget

Outputs Widget objects representing the retrieved widgets.

NOTAS H2

A seção NOTAS contém informações adicionais sobre o cmdlet. A seção pode estar vazia, mas o cabeçalho H2 é necessário. Você pode usar esta seção para documentar considerações especiais, limitações, diferenças de versão e informações que não se encaixam em outras seções.

H2 LINKS RELACIONADOS

A seção LINKS RELACIONADOS contém links para tópicos relacionados. A seção pode estar vazia, mas o cabeçalho H2 é necessário. Os links devem ser formatados como uma lista com marcadores de links Markdown. Esta secção não deve conter qualquer outro conteúdo.

## RELATED LINKS

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

Próximos passos

• Testar os arquivos de ajuda do Markdown