將自定義 GitHub 徽章添加到您的代碼庫

語言: CN / TW / HK

如果你花時間看 GitHub 上的開源倉庫,你可能已經注意到他們中的大多數在 README 文件中使用了徽章。以官方的 React 倉庫為例,在 README 文件中到處都有 GitHub 的徽章,傳達重要的動態信息,比如最新發布的版本和當前的構建是否通過。

像這樣的徽章提供了一種很好的方式來強調版本庫的關鍵信息。你甚至可以使用你自己的自定義資產作為徽章,就像 Next.js 在其倉庫中所做的那樣。

但到目前為止,GitHub 徽章最有用的地方在於它們會自行更新。GitHub 中的標記可以自動從遠程服務器獲取更改,而不是將值硬編碼到您的 README 中。

讓我們討論一下如何在自己項目的 README 文件中添加動態 GitHub 徽章。我們將首先使用一個名為 badgen.net [1] 的在線生成器來創建一些基本的徽章。然後,我們將通過 Napkin [2] 將徽章與我們自己的 Serverless 函數掛鈎,使其成為動態徽章。最後,我們將通過使用我們自己的自定義 SVG 文件,使事情更進一步。

首先:徽章是如何工作的?

在我們開始在 GitHub 中建立一些徽章之前,讓我們快速瀏覽一下它們是如何實現的。這其實很簡單:徽章就是圖片。README 文件是用 Markdown 寫的,而 Markdown 支持圖片,就像這樣。

!\[alt text\](path or URL to image "alt text\")

我們可以包含一個圖片的 URL,這意味着一個 Markdown 頁面在渲染時將從服務器上請求圖片數據。 所以,如果我們控制了擁有圖像的服務器,我們就可以用我們想要的任何邏輯來改變送回來的圖像!

值得慶幸的是,我們有幾個選擇來部署我們自己的服務器邏輯,而不需要整個 "設置服務器 "部分。對於基本用例,我們可以使用 badgen.net [3] 的預定義模板來創建 GitHub 徽章圖片。同樣, Napkin [4] 可以讓我們在瀏覽器中快速編寫 Serverless 函數,然後將其部署為 GitHub 徽章可以對話的端點。

使用 Badgen 製作徽章

讓我們從最簡單的徽章解決方案開始:通過 badgen.net [5] 製作靜態徽章。Badgen API 使用 URL 模式來即時創建模板化的徽章。該 URL 模式如下:

https://badgen.net/badge/:subject/:status/:color?icon=github

badgen.net [6] 上有一個關於顏色、圖標等選項的完整列表。在這個例子中,讓我們使用這些值:

  • :subject: : Hello
  • :status: : World
  • :color: : red
  • :icon: : twitter

我們的最終 URL 看起來像這樣:

https://badgen.net/badge/hello/world/red?icon=twitter

查看此徽章:https://badgen.net/badge/hello/world/red?icon=twitter

將 GitHub 徽章添加到 README 文件

現在我們需要將此徽章嵌入到 GitHub 存儲庫的 README 文件中。我們可以使用我們之前看到的語法在 Markdown 中做到這一點:

![my badge](https://badgen.net/badge/hello/world/red?icon=twitter "my badge\")

Badgen 提供了大量不同的選項,所以我鼓勵你去他們的網站看看,玩一玩。例如,其中一個模板可以讓你顯示某個 GitHub 代碼庫被加星的次數。 以 Next.js repo 為例,這裏有一個 GitHub 星級徽章 [7]

https://badgen.net/github/stars/vercel/next.js

查看徽章 [8]

很酷!但是,如果您希望您的徽章顯示一些 Badgen 本身不支持的信息怎麼辦?幸運的是,Badgen 有一個 URL 模板,用於使用您自己的 HTTPS 端點來獲取數據:

https://badgen.net/https/url/to/your/endpoint

例如,假設我們希望我們的徽章以美元顯示比特幣的當前價格。我們所需要的只是一個自定義端點,它以 JSON 格式返回此數據,如下所示:

{
  "color": "blue",
  "status": "$39,333.7",
  "subject": "Bitcoin Price USD"
}

假設我們的端點在 https://some-endpoint.example.com/bitcoin 可用,我們可以使用以下 URL 方案將其數據傳遞給 Badgen:

https://badgen.net/https/some-endpoint.example.com/bitcoin

現在更酷了!但我們仍然必須實際創建為 GitHub 徽章提供數據的端點。 這讓我們……

Badgen + Napkin

有很多方法可以獲取您自己的 HTTPS 端點。您可以使用 DigitalOcean 或 AWS EC2 啟動服務器,也可以使用無服務器選項,如 Google Cloud Functions 或 AWS Lambda;但是,對於我們的簡單用例來説,這些仍然會變得有點複雜和乏味。這就是為什麼我建議 Napkin 的瀏覽器內功能編輯器 [9] 無需任何安裝或配置即可編碼和部署端點。

要將端點與 Badgen 一起使用,請使用與上面相同的 URL 方案,只是這次使用的是 Napkin 端點:

https://badgen.net/https/napkin-examples.npkn.net/bitcoin-badge

查看徽章:https://badgen.net/https/napkin-examples.npkn.net/bitcoin-badge

更多自定義 GitHub 徽章的方法

接下來,讓我們 fork 這個函數 [10] ,這樣我們就可以向它添加我們自己的自定義代碼。單擊右上角的“fork”按鈕即可。如果您尚未登錄,系統會提示您使用 Napkin 創建一個帳户。

一旦我們成功地 fork 了這個函數,我們就可以添加任何我們想要的代碼,使用任何我們想要的 npm 模塊。讓我們添加 Moment.js npm 包 [11] ,並更新端點響應,在我們的 GitHub 徽章中直接顯示比特幣的價格最後更新的時間。

import fetch from 'node-fetch'
import moment from 'moment'

const bitcoinPrice = async () => {
  const res = await fetch("<https://blockchain.info/ticker>")
  const json = await res.json()
  const lastPrice = json.USD.last+""

  const [ints, decimals] = lastPrice.split(".")

  return ints.slice(0, -3) + "," + ints.slice(-3) + "." + decimals
}

export default async (req, res) => {
  const btc = await bitcoinPrice()

  res.json({
    icon: 'bitcoin',
    subject: `Bitcoin Price USD (${moment().format('h:mma')})`,
    color: 'blue',
    status: `\\$${btc}`
  })
}

你可能會注意到,當你下次在 GitHub 上加載 README 文件時,徽章需要一些時間來刷新。這是因為 GitHub 使用了一個代理機制來提供徽章圖片。

GitHub 這樣提供徽章圖片是為了防止濫用,比如高請求量或 JavaScript 代碼注入。我們無法控制 GitHub 的代理,但幸運的是,它不會太積極地進行緩存(否則就有點違背了徽章的目的)。根據我的經驗,TTL 大約是 5-10 分鐘。

用 Napkin 定製 SVG 徽章

對於我們的最後一個技巧,讓我們使用 Napkin 發回一個全新的 SVG,這樣我們就可以使用我們在 Next.js 存儲庫中看到的自定義圖像。

GitHub 徽章的一個常見用例是顯示一個網站的當前狀態。讓我們來做這件事。下面是我們的徽章將支持的兩種狀態:

Badgen 不支持自定義 SVG,因此,我們將讓我們的徽章直接與我們的 Napkin 端點對話。讓我們為此創建一個名為 site-status-badge 的新 Napkin 函數。

這個函數中的代碼向 example.com 發出了一個請求。如果請求狀態是 200,它將綠色徽章作為一個 SVG 文件返回;否則,它將返回紅色徽章。你可以 查看這個函數 [12] ,但我也會把代碼放在這裏供參考:

import fetch from 'node-fetch'

const site_url = "<https://example.com>"

// full SVGs at <https://napkin.io/examples/site-status-badge>
const customUpBadge = ''
const customDownBadge = ''

const isSiteUp = async () => {
  const res = await fetch(site_url)
  return res.ok
}

export default async (req, res) => {
  const forceFail = req.path?.endsWith('/400')

  const healthy = await isSiteUp()
  res.set('content-type', 'image/svg+xml')
  if (healthy && !forceFail) {
    res.send(Buffer.from(customUpBadge).toString('base64'))
  } else {
    res.send(Buffer.from(customDownBadge).toString('base64'))
  }
}

example.com 網站出現故障的可能性非常低,因此我添加了 forceFail 案例來模擬這種情況。現在我們可以在 Napkin 端點 URL 後添加 /400 來嘗試一下:

![status up](https://napkin-examples.npkn.net/site-status-badge/ "status up\")
![status down](https://napkin-examples.npkn.net/site-status-badge/400 "status down\")

非常好 :sunglasses:

這就是我們的成果!你的 GitHub 徽章培訓已經完成。但這一旅程還遠未結束,像這樣的徽章在很多方面都有很大的幫助。祝你實驗愉快,讓 README 熠熠生輝吧!

原文:https://css-tricks.com/adding-custom-github-badges-to-your-repo/
作者:Nick Sypteras

往期精文

參考資料

[1]

badgen.net: http://badgen.net/

[2]

Napkin: http://napkin.io/

[3]

badgen.net: http://badgen.net/

[4]

Napkin: http://napkin.io/

[5]

badgen.net: http://badgen.net/

[6]

badgen.net: http://badgen.net/

[7]

以 Next.js repo 為例,這裏有一個 GitHub 星級徽章: https://badgen.net/github/stars/vercel/next.js

[8]

查看徽章: https://badgen.net/github/stars/vercel/next.js

[9]

Napkin 的瀏覽器內功能編輯器: https://www.napkin.io/sandbox

[10]

fork 這個函數: https://napkin.io/examples/bitcoin-badge

[11]

Moment.js npm 包: https://www.npmjs.com/package/moment/v/1.1.0

[12]

查看這個函數: https://napkin.io/examples/site-status-badge