通过

使用 Microsoft.PowerShell.PlatyPS 更新 Markdown 帮助文件

在 PowerShell 模块的生命周期中，可以添加新的命令和参数或更改现有参数。 发布新版本的模块时，应更新模块的 Markdown 帮助文件，以确保帮助内容准确完整。

和 Update-MarkdownCommandHelp 命令Update-MarkdownModuleFile更新 Markdown 文件以反映模块中的更改。 要更新内容，必须先将更新的模块导入到当前会话中。 update 命令导入现有的 Markdown 文件，并根据当前会话中加载的模块更新内容。 这些命令在进行更改之前创建现有内容的备份。 您可以将更新的文件与备份文件进行比较，以查看更改的内容。

您可以使用更新命令将较旧的 Markdown 文件转换为 PlatyPS 格式。 这些命令可以导入以前版本的 PlatyPS （platyPS v0.14.2） 创建的 Markdown 文件。 但是，更新内容的格式是使用 PlatyPS Markdown 格式编写的。

更新命令 Markdown 文件

使用该 Update-MarkdownCommandHelp 命令更新命令 Markdown 文件。 例如：

Import-Module -Name 'YourModuleName' -Force # Load the updated module
Measure-PlatyPSMarkdown -Path ./docs/YourModuleName/*.md
    Where-Object Filetype -match 'CommandHelp' |
    Update-MarkdownCommandHelp -Path {$_.FilePath}

您必须检查每个更新的文件，以确保内容正确且完整。 如果您要将较旧的 Markdown 文件转换为 PlatyPS 格式，则必须编辑一个新 ## ALIASES 部分。 本节用于记录为命令定义的任何别名。 此部分是可选的，如果没有别名，则可以删除。 您还需要添加任何新示例并记录任何新参数。

更新模块 Markdown 文件

完成编辑和测试命令 Markdown 文件后，可以使用该 Update-MarkdownModuleFile 命令更新模块 Markdown 文件。 例如：

Measure-PlatyPSMarkdown -Path ./docs/YourModuleName/*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    Update-MarkdownModuleFile -Path ./docs/YourModuleName/YourModuleName.md

请务必检查更新的模块文件，以确保内容正确且完整。

将更改与备份文件进行比较

该命令向 Update-MarkdownCommandHelp 现有命令 Markdown 文件添加新信息，但在更改现有内容方面是保守的。 添加到 Markdown 的任何新信息都包含占位符字符串，您必须将其替换为准确的信息。 此外，帮助文件中还有无法准确更新的项目。 例如：

  • PlatyPS 命令通过使用 Get-Command检查命令来获取输出类型信息。 但是，如果命令作者未定义输出类型，则输出类型信息不完整。 可以在 Markdown 文件中添加输出类型信息。 Update-MarkdownCommandHelp 仅添加可以验证的输出类型信息，但不会删除任何现有的输出类型信息。

  • 同样，某些参数允许您使用通配符表达式。 如果命令作者将属性添加到 [SupportsWildcards()] 参数，则该信息将正确反映在 markdown 文件中。 但是，命令作者省略该属性是很常见的。 可以更改 Markdown 文件中的参数信息，以指示支持通配符。 您需要确保更新的信息正确无误。

为获得最佳结果，请使用文件比较工具将更新的文件与备份文件进行比较。 您可以使用 Visual Studio Code 或 Beyond Compare 等比较工具进行并排比较。

完成更新后，您可以删除备份文件。

后续步骤

以下文章介绍 Markdown 文件的结构，以及如何确保内容遵循预期格式。

  • Last updated on