共用方式為

編輯器的檢查清單

本文包含撰寫或編輯 PowerShell 檔案的摘要規則清單。 如需這些規則的詳細說明和範例，請參閱參與者指南中的其他文章。

後設資料

  • ms.date：格式必須是 MM/DD/YYYY
    • 當有重大或事實更新時，變更日期
      • 重新組織文章
      • 修正事實錯誤
      • 新增資訊
    • 如果更新不重要，請勿變更日期
      • 修正錯字和格式設定
  • 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、 輸出或其他適當的語言識別碼
  • 針對語法區塊使用未標記的程式代碼柵欄
  • 除了您不想讓讀取者使用 [ 複製 ] 按鈕的基本範例之外，將輸出放入個別的程式代碼區塊中
  • 請參閱支援的語言清單

清單

  • 正確縮排
  • 在第一個項目和最後一個項目之後新增空白行
  • 使用短橫線（-）作為項目符號而不是星號（*），以減少與強調的混淆。
  • 使用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屬性的網址中包含地區設定（從網址移除 /en-us ）
    • 除非對目標網站無效，否則外部網站的所有 URL 都應該使用 HTTPS
  • 在 docset 中建立連結時
    • 使用相對檔案路徑 （../folder/file.md）
  • 所有路徑都使用正斜線 （/） 字元
  • 影像連結應具有唯一的替換文字
  • Last updated on