Hinzufügen benutzerdefinierter GitHub-Badges zu Ihrem Repository

Wenn Sie Zeit damit verbracht haben, Open-Source-Repositorys auf GitHub zu betrachten, haben Sie wahrscheinlich bemerkt, dass die meisten davon Badges in ihren README-Dateien verwenden. Nehmen Sie zum Beispiel das offizielle React-Repository. Es gibt GitHub-Badges überall in der README-Datei, die wichtige dynamische Informationen kommunizieren, wie die neueste veröffentlichte Version und ob der aktuelle Build erfolgreich ist.

Badges wie diese bieten eine gute Möglichkeit, wichtige Informationen über ein Repository hervorzuheben. Sie können sogar Ihre eigenen benutzerdefinierten Assets als Badges verwenden, wie es Next.js in seinem Repository tut.

Aber das Nützlichste an GitHub-Badges ist bei weitem, dass sie sich von selbst aktualisieren. Anstatt Werte fest in Ihre README zu codieren, können Badges in GitHub automatisch Änderungen von einem Remote-Server übernehmen.

Lassen Sie uns besprechen, wie Sie dynamische GitHub-Badges zur README-Datei Ihres eigenen Projekts hinzufügen. Wir beginnen mit einem Online-Generator namens badgen.net, um einige grundlegende Badges zu erstellen. Dann machen wir unsere Badges dynamisch, indem wir sie über Napkin mit unserer eigenen serverlosen Funktion verbinden. Schließlich gehen wir noch einen Schritt weiter, indem wir unsere eigenen benutzerdefinierten SVG-Dateien verwenden.

Zuerst: Wie funktionieren Badges?

Bevor wir mit dem Erstellen von Badges in GitHub beginnen, werfen wir einen kurzen Blick darauf, wie sie implementiert werden. Es ist eigentlich sehr einfach: Badges sind nur Bilder. README-Dateien sind in Markdown geschrieben, und Markdown unterstützt Bilder wie folgt

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

Die Tatsache, dass wir eine URL zu einem Bild einfügen können, bedeutet, dass eine Markdown-Seite die Bilddaten von einem Server anfordert, wenn die Seite gerendert wird. Wenn wir also den Server kontrollieren, der das Bild hat, können wir mit jeder gewünschten Logik ändern, welches Bild zurückgesendet wird!

Glücklicherweise haben wir ein paar Optionen, um unsere eigene Serverlogik bereitzustellen, ohne den ganzen Teil des „Einrichtens des Servers“. Für grundlegende Anwendungsfälle können wir unsere GitHub-Badge-Bilder mit badgen.net unter Verwendung seiner vordefinierten Vorlagen erstellen. Und wieder, Napkin ermöglicht es uns, schnell eine serverlose Funktion in unserem Browser zu programmieren und sie dann als Endpunkt bereitzustellen, mit dem unsere GitHub-Badges kommunizieren können.

Badges mit Badgen erstellen

Beginnen wir mit der einfachsten Badge-Lösung: einem statischen Badge über badgen.net. Die Badgen-API verwendet URL-Muster, um Vorlagen-Badges im laufenden Betrieb zu erstellen. Das URL-Muster lautet wie folgt

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

Es gibt eine vollständige Liste der Optionen für Farben, Icons und mehr auf badgen.net. Für dieses Beispiel verwenden wir diese Werte

• :subject : Hallo
• :status: : Welt
• :color: : rot
• :icon: : twitter

Unsere endgültige URL sieht dann so aus

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

Ein GitHub-Badge zur README-Datei hinzufügen

Nun müssen wir diesen Badge in die README-Datei unseres GitHub-Repositorys einbetten. Das können wir in Markdown mit der Syntax tun, die wir bereits besprochen haben

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

Badgen bietet eine Vielzahl von Optionen, daher ermutige ich Sie, deren Website zu besuchen und herumzuspielen! Zum Beispiel zeigt eine der Vorlagen die Anzahl der Sterne an, die ein bestimmtes GitHub-Repository erhalten hat. Hier ist ein Stern-GitHub-Badge für das Next.js-Repository als Beispiel

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

Ziemlich cool! Aber was ist, wenn Ihr Badge Informationen anzeigen soll, die Badgen nicht nativ unterstützt? Glücklicherweise hat Badgen eine URL-Vorlage für die Verwendung Ihrer eigenen HTTPS-Endpunkte zur Datenabfrage

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

Nehmen wir zum Beispiel an, wir möchten, dass unser Badge den aktuellen Preis von Bitcoin in USD anzeigt. Alles, was wir brauchen, ist ein benutzerdefinierter Endpunkt, der diese Daten als JSON wie folgt zurückgibt

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

Angenommen, unser Endpunkt ist unter https://some-endpoint.example.com/bitcoin verfügbar, können wir seine Daten mit dem folgenden URL-Schema an Badgen übergeben

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

Noch cooler! Aber wir müssen immer noch den Endpunkt erstellen, der die Daten für das GitHub-Badge liefert. 🤔 Was uns zu…

Badgen + Napkin

Es gibt viele Möglichkeiten, Ihren eigenen HTTPS-Endpunkt zu erhalten. Sie könnten einen Server mit DigitalOcean oder AWS EC2 aufsetzen oder eine serverlose Option wie Google Cloud Functions oder AWS Lambda nutzen; diese können jedoch für unseren einfachen Anwendungsfall immer noch etwas komplex und mühsam sein. Deshalb schlage ich Napkins In-Browser-Funktionseditor vor, um einen Endpunkt zu codieren und bereitzustellen, ohne Installationen oder Konfigurationen.

Gehen Sie zu Napkins Bitcoin-Badge-Beispiel, um einen Beispielendpunkt zu sehen. Sie können den Code zum Abrufen des aktuellen Bitcoin-Preises und zur Rückgabe als JSON im Editor sehen. Sie können den Code selbst aus dem Editor ausführen oder den Endpunkt direkt verwenden.

Um den Endpunkt mit Badgen zu verwenden, arbeiten Sie mit demselben URL-Schema wie oben, nur dieses Mal mit dem Napkin-Endpunkt

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

Weitere Möglichkeiten zur Anpassung von GitHub-Badges

Als Nächstes forken wir diese Funktion, damit wir unseren eigenen benutzerdefinierten Code hinzufügen können. Klicken Sie dazu auf die Schaltfläche „Fork“ oben rechts. Sie werden aufgefordert, ein Konto bei Napkin zu erstellen, falls Sie noch nicht angemeldet sind.

Sobald wir die Funktion erfolgreich geforkt haben, können wir beliebigen Code mit beliebigen npm-Modulen hinzufügen. Fügen wir das npm-Paket Moment.js hinzu und aktualisieren die Endpunktantwort, um die Uhrzeit anzuzeigen, zu der der Bitcoin-Preis zuletzt aktualisiert wurde, direkt in unserem GitHub-Badge

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}`
  })
}

Möglicherweise stellen Sie fest, dass das Aktualisieren des Badges beim nächsten Laden der README-Datei auf GitHub einige Zeit dauert. Das liegt daran, dass GitHub einen Proxy-Mechanismus zum Bereitstellen von Badge-Bildern verwendet.

GitHub stellt die Badge-Bilder auf diese Weise bereit, um Missbrauch zu verhindern, wie z. B. hohe Anfragewerte oder die Einschleusung von JavaScript-Code. Wir können den GitHub-Proxy nicht kontrollieren, aber glücklicherweise cached er nicht zu aggressiv (denn sonst würde das den Zweck von Badges ziemlich untergraben). Meiner Erfahrung nach liegt die TTL bei etwa 5-10 Minuten.

Okay, Zeit für den letzten Boss.

Benutzerdefinierte SVG-Badges mit Napkin

Für unseren letzten Trick verwenden wir Napkin, um ein komplett neues SVG zurückzusenden, damit wir benutzerdefinierte Bilder verwenden können, wie wir sie im Next.js-Repository gesehen haben.

Ein häufiger Anwendungsfall für GitHub-Badges ist die Anzeige des aktuellen Status einer Website. Machen wir das. Hier sind die beiden Zustände, die unser Badge unterstützen wird

Badgen unterstützt keine benutzerdefinierten SVGs. Stattdessen lassen wir unser Badge direkt mit unserem Napkin-Endpunkt kommunizieren. Erstellen wir eine neue Napkin-Funktion dafür namens site-status-badge.

Der Code in dieser Funktion macht eine Anfrage an example.com. Wenn der Status der Anfrage 200 ist, gibt er das grüne Badge als SVG-Datei zurück; andernfalls gibt er das rote Badge zurück. Sie können die Funktion überprüfen, aber ich füge den Code hier auch als Referenz ein

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'))
  }
}

Die Wahrscheinlichkeit, dass die Seite example.com jemals ausfällt, ist gering, daher habe ich die forceFail-Option hinzugefügt, um dieses Szenario zu simulieren. Jetzt können wir /400 nach der Napkin-Endpunkt-URL hinzufügen, um es auszuprobieren

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

Sehr schön 😎

---

Und da haben wir es! Ihr GitHub-Badge-Training ist abgeschlossen. Aber die Reise ist noch lange nicht zu Ende. Es gibt unzählige Dinge, bei denen solche Badges super hilfreich sind. Viel Spaß beim Experimentieren und lassen Sie Ihre README glänzen! ✨