若要在 Discord 或專案 README 中使用自訂徽章，請使用 徽章產生器建立靜態 Shields.io 圖片、預覽，並複製直接 URL、Markdown 程式碼片段或 HTML 標籤。此工作流程適用於自訂專案徽章，而非授予或附加 Discord 帳號徽章。產生器可讓您定義左側標籤、右側訊息、顏色、支援的樣式及選用的 Simple Icons 標誌，接著產生標準化的 Shields.io URL，以及相符的 Markdown 和 HTML 輸出。您可以在接受遠端徽章圖片的目的地中使用圖片 URL、將 Markdown 貼到儲存庫文件中，或在支援標記語言的網站上使用 HTML。由於產生器會處理路徑分隔符號、逸出及查詢參數，因此徽章在維持易讀性的同時，底層 URL 仍保持正確。不過，結果是靜態的，因此適合用於您願意維護的穩定標籤、版本、連結或狀態說明，而非作為建置、稽核或覆蓋率報告的自動證明。
徽章工作流程實際會建立什麼
當您想在 README、文件頁面、發行說明或專案儀表板中使用自訂狀態徽章時，請使用此工作流程。如果目的地接受附件或遠端圖片，產生的圖片也能支援面向 Discord 的工作流程，但此工具不會在 Discord 使用者個人檔案上核發徽章。這項差異很重要：產生的徽章是呈現內容，而個人檔案徽章則是此產生器以外的帳號功能。
所有三種輸出都衍生自同一個標準化的 Shields.io URL。請依據將顯示輸出的目的地選擇格式，然後測試該目的地，而不是只評估格式本身。
| 輸出 | 最適合的用途 | 應驗證的項目 |
|---|---|---|
| 直接圖片 URL | 接受遠端徽章圖片的系統，或供 Discord 附件使用的瀏覽器下載 | 圖片可以開啟，且文字、標誌和顏色均正確顯示 |
| Markdown | GitHub 或 GitLab README、議題範本及文件檔案 | 儲存庫目的地會依預期呈現徽章 |
| HTML | 接受圖片標記語言的網站 | 圖片來源可載入，且逸出後的替代文字描述仍然實用 |
選擇文字、顏色、樣式及標誌
請先使用簡短的標籤指出主題，例如 build、docs、version 或 license，再接上簡潔的訊息。標籤和訊息必須包含可見文字、維持在實用的長度限制內，且不得含有控制字元。文字應精簡到能以徽章實際顯示的尺寸快速瀏讀，並避免將顏色作為解釋含義的唯一方式。
| 欄位 | 接受的輸入 | 控制的項目 |
|---|---|---|
| 標籤 | 實用長度限制內的可見文字，且不含控制字元 | 徽章左側的文字 |
| 訊息 | 實用長度限制內的可見文字，且不含控制字元 | 徽章右側的文字 |
| 訊息顏色 | 精簡的具名形式或三位數或六位數的十六進位值；可選擇移除開頭的井字號 | 訊息背後的背景 |
| 標籤顏色 | 使用接受的顏色形式的選用顏色 | 標籤背後的背景 |
| 樣式 | 其中一種支援的樣式 | 徽章的整體視覺呈現 |
| 標誌 | 選用值，必須看起來像 Simple Icons 的 slug | 徽章文字旁的選用標誌 |
以四個步驟建立徽章
- 輸入兩個文字欄位。開啟徽章產生器，在左側欄位輸入簡短的標籤。新增應顯示在右側的簡潔狀態、版本、連結文字或其他訊息。
- 設定外觀。選擇具名或十六進位的訊息顏色、選用的標籤顏色，以及支援的樣式。請將各選項與周圍頁面比較，確保徽章仍然清楚易讀。
- 新增標誌並檢查預覽。選擇性地輸入 Simple Icons 的 slug，然後確認即時的 Shields.io 預覽顯示預期的文字、顏色、樣式及圖示。
- 複製適當的輸出。選擇圖片 URL、Markdown 或 HTML，將其貼到預定目的地，並測試呈現結果。請勿僅憑預覽就認定最終頁面或訊息能正確顯示。
在 Discord 上新增自訂徽章，勿與個人檔案徽章混淆
徽章產生器不會直接發布至 Discord。它的工作會在提供圖片 URL 和兩個相符的程式碼片段後結束。若要得到面向 Discord 的結果，請選擇適當的傳送方式：當目的地接受該圖片格式時，將徽章圖片附加至訊息；或將 Markdown 徽章放在儲存庫 README 中，並分享呈現後的專案頁面。
- 選擇 Discord 情境。決定徽章要放在頻道訊息、從 Discord 連結的專案 README，或您維護的其他頁面中。如此可避免自訂專案徽章被誤認為官方帳號徽章。
- 產生並確認徽章。輸入標籤和訊息，選擇顏色與樣式，必要時新增標誌，並在複製任何內容前驗證即時預覽。
- 在適當情況下準備頻道附件。複製直接圖片 URL，在瀏覽器中開啟；若目標接受該檔案格式，請附加下載的圖片。Markdown 和 HTML 輸出是供支援這些格式的目的地使用，因此不要將它們硬塞進預期要接收圖片附件的訊息中。
- 對專案文件使用共用的 README 方式。將 Markdown 程式碼片段複製到相關的 README。GitLab 專案徽章文件說明專案徽章可顯示的位置，而相同的 Markdown 方法也適用於以 GitHub 為基礎的文件。
- 測試最終體驗。開啟已發布的儲存庫或檢查已傳送的訊息。在情境重要時，加入周圍說明文字及有意義的替代文字描述，並請記住平台代理可能會快取遠端圖片。
此方法能為面向 Discord 的內容新增自訂視覺素材，而不會聲稱該圖片是官方 Discord 個人檔案徽章。
為何複製產生的 URL，而非手動建立
手寫的靜態徽章 URL 包含多個組成部分。標籤、訊息及核心顏色遵循結構化路徑，而選用的樣式、標籤顏色及標誌值則屬於查詢參數。可見文字中的常破折號與底線會加倍，是因為 Shields.io 使用這些字元來編碼空格並分隔徽章各部分。其他特殊字元則會經過 URL 編碼。任何一項規則處理錯誤，都可能改變可見文字或破壞路徑。
產生器會套用文件記載的逸出規則，並透過 URLSearchParams 加入支援的選項。接著從同一個標準化 URL 衍生 Markdown 和 HTML 程式碼片段，讓三種輸出保持一致。若您需要了解路徑結構，Shields.io 靜態徽章參考資料會說明其底層 URL 模型。
驗證程序會嚴格檢查含糊或 unsafe 的輸入，但無法保證每個外部資源都存在。表單會檢查顏色是否符合接受的形式，以及標誌值是否看起來像 Simple Icons 的 slug，但不會確認每個具名顏色或標誌目前是否存在於外部服務。如果標誌無法顯示，請將 slug 與目前的 Simple Icons 目錄比較，再重新產生徽章。
檢查預覽與最終目的地
徽章產生作業在你的瀏覽器中進行，此工具不需要帳號，也不會儲存徽章歷史。預覽本身是從 Shields.io 載入，因此顯示預覽時會向該提供者發出網路請求。你的表單資料不會發布至 Lizely，但 Shields.io 會收到呈現預覽所需的圖片請求。
請以徽章實際顯示的尺寸預覽數種樣式。在產生器中看起來平衡的徽章，在狹窄的行動裝置螢幕上可能需要不同的周圍間距或更簡潔的訊息。複製輸出後，請測試實際的 README、網站或 Discord 附件。HTML 輸出提供逸出後的 alt 屬性與圖片來源，因此適合支援標記語言的網站。如果目標平台會代理遠端圖片，更新後的徽章可能仍快取於產生器之外，因此檢查目的地後再認定變更失敗。
發布後維持靜態徽章的準確性
產生的徽章只用於呈現，並非驗證。手動輸入 passing、secure 或 100% 等訊息，並不能確認建置已執行、稽核已通過或覆蓋率已達到該水準。它只會顯示您選擇的文字。對於必須自動變更的事實，請使用由相關 CI 系統、套件登錄中心或經驗證端點支援的徽章。靜態徽章更適合用於您願意維護的穩定標籤、連結、版本及狀態說明。
請為每個徽章提供足夠的周圍脈絡，讓其無須依賴顏色仍有意義。簡短的句子、描述性的連結文字或有意義的替代文字描述，都能說明標籤代表什麼以及通往何處。當徽章顯示在其他狀態指標旁，或讀者無法區分顏色時，這尤其實用。目標是提供精簡的視覺提示，並確保其內容準確、易於理解且容易維護。