通过

编辑的检查清单

本文包含用于编写或编辑 PowerShell 文档的规则汇总列表。 有关这些规则的详细说明和示例，请参阅参与者指南中的其他文章。

元数据

  • ms.date：必须采用 MM/DD/YYYYY 格式
    • 在发生重大更新或事实更新时更改日期
      • 重新组织文章
      • 修复事实错误
      • 添加新信息
    • 如果更新无关紧要，请不要更改日期
      • 修复拼写错误和格式设置
  • title：长度为 43-59 个字符的唯一字符串（包括空格）
    • 不要包含站点标识符（它自动生成）
    • 使用句子大小写 - 仅大写第一个单词和任何专有名词
  • description：包含空格的 115-145 个字符 - 此摘要显示在搜索结果中

格式化

  • 段落中以内联形式显示的反引号语法元素
    • Cmdlet 名称 Verb-Noun
    • 变量 $counter
    • 语法示例 Verb-Noun -Parameter
    • 文件路径 C:\Program Files\PowerShell， /usr/bin/pwsh
    • 不应在文档中单击的 URL
    • 属性或参数值
  • 对属性名称、参数名称、类名称、模块名称、实体名称、对象或类型名称使用粗体
    • 粗体用于语义标记，而不是强调
    • 粗体 - 使用星号 **
  • 斜体 - 使用下划线 _
    • 仅用于强调，不适用于语义标记
  • 在 100 字符处换行（或者在 about_Topics 内换行到 80 字符）
  • 没有硬选项卡 - 仅使用空格
  • 行内没有尾随空格
  • PowerShell 关键字和运算符应全部小写
  • 对 cmdlet 名称和参数使用适当的 （Pascal） 大小写

标头

  • 首先从 H1 开始 - 每篇文章只有一个 H1
  • 仅使用 ATX 标头
  • 对所有标题使用首字母大写格式
  • 不要跳级——在没有 H2 的情况下不能有 H3
  • 将标头深度限制为 H3 或 H4
  • 在前后添加空白行
  • 不要添加或删除标头 - PlatyPS 在其架构中强制实施特定标头

代码块

  • 在前后添加空白行
  • 使用标记的代码围栏 - powershell、 Output或其他适当的语言 ID
  • 对语法块使用未标记的代码围栏
  • 将输出放在单独的代码块中，除非基本示例不需要读者使用 “复制” 按钮的情况
  • 请参阅支持的语言列表

列表

  • 正确缩进
  • 在第一项和最后一项之后添加空白行
  • 使用连字符（-）作为列表符号而不是星号（*），以避免与强调符号混淆。
  • 请使用 1. 编号列表中的所有项

术语

  • 使用 PowerShell 与 Windows PowerShell
  • 请参阅 产品术语

Cmdlet 参考示例

  • cmdlet 引用中必须至少有一个示例

  • 示例应只有足够多的代码来演示用法

  • PowerShell 语法

    • 使用 cmdlet 和参数的完整名称 - 无别名
    • 当命令行过长时，使用 splatting 技术来管理参数
    • 避免使用行延续反引号——仅在必要时使用

  • 删除或简化 PowerShell 提示（PS>），除非示例需要。

  • Cmdlet 参考示例必须遵循以下 PlatyPS 架构

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • 不要在代码块之间放置段落。 所有描述性内容都必须在代码块之前或之后出现。

链接到其他文档

  • 在文档集外部链接或在 cmdlet 引用和概念之间链接时
    • 链接到 Microsoft Learn 时，请使用相对网站的 URL，并删除 https://learn.microsoft.com/en-us
    • 不要在 Microsoft 资源的 URL 中包含区域设置（从 URL 中删除 /en-us）
    • 外部网站的所有 URL 都应使用 HTTPS，除非该 URL 对目标网站无效
  • 在文档集内链接时
    • 使用相对文件路径 （../folder/file.md）
  • 所有路径都使用正斜杠 （/） 字符
  • 图像链接应具有唯一的替换文字