Als je tijd hebt besteed aan het bekijken van open-source repo's op GitHub, heb je waarschijnlijk gemerkt dat de meeste van hen badges gebruiken in hun README-bestanden. Neem bijvoorbeeld de officiële React-repository. Er zijn GitHub-badges overal in het README-bestand die belangrijke dynamische informatie communiceren, zoals de nieuwste vrijgegeven versie en of de huidige build doorgaat.
Badges zoals deze bieden een leuke manier om belangrijke informatie over een repository te markeren. Je kunt zelfs je eigen aangepaste middelen als badges gebruiken, zoals Next.js doet in zijn repo.
Maar verreweg het handigste aan GitHub-badges is dat ze worden bijgewerkt zelf. In plaats van waarden hard te coderen in uw README, kunnen badges in GitHub automatisch wijzigingen oppikken van een externe server.
Laten we bespreken hoe u dynamische GitHub-badges kunt toevoegen aan het README-bestand van uw eigen project. We beginnen met het gebruik van een online generator genaamd badgen.net om enkele basisbadges te maken. Vervolgens maken we onze badges dynamisch door ze aan onze eigen serverloze functie te koppelen via Servet. Ten slotte gaan we nog een stap verder door onze eigen aangepaste SVG-bestanden te gebruiken.
Ten eerste: hoe werken badges?
Voordat we beginnen met het bouwen van enkele badges in GitHub, laten we snel kijken hoe ze worden geïmplementeerd. Het is eigenlijk heel simpel: badges zijn slechts afbeeldingen. README-bestanden zijn geschreven in Markdown en Markdown ondersteunt afbeeldingen zoals:
Het feit dat we een URL naar een afbeelding kunnen opnemen, betekent dat een Markdown-pagina de afbeeldingsgegevens van een server zal opvragen wanneer de pagina wordt weergegeven. Dus, als we de server besturen die de afbeelding heeft, kunnen we veranderen welke afbeelding wordt teruggestuurd met elke logica die we willen!
Gelukkig hebben we een aantal opties om onze eigen serverlogica in te zetten zonder het hele "het opzetten van de server" -gedeelte. Voor basisgebruik kunnen we onze GitHub-badgeafbeeldingen maken met badgen.net met behulp van de vooraf gedefinieerde sjablonen. En opnieuw, Servet laat ons snel een serverloze functie coderen in onze browser en deze vervolgens implementeren als een eindpunt waarmee onze GitHub-badges kunnen communiceren.
Badges maken met Badgen
Laten we beginnen met de eenvoudigste badge-oplossing: een statische badge via badgen.net. De Badgen API gebruikt URL-patronen om direct sjabloonbadges te maken. Het URL-patroon is als volgt:
https://badgen.net/badge/:subject/:status/:color?icon=githubEr is een volledige lijst van de opties die je hebt voor kleuren, pictogrammen en meer op badgen.net. Laten we voor dit voorbeeld deze waarden gebruiken:
:subject: Hallo:status:: Wereld:color:: rood:icon:: twitteren
Onze uiteindelijke URL ziet er uiteindelijk als volgt uit:
https://badgen.net/badge/hello/world/red?icon=twitterEen GitHub-badge toevoegen aan het README-bestand
Nu moeten we deze badge insluiten in het README-bestand van onze GitHub-repo. We kunnen dat doen in Markdown met behulp van de syntaxis die we eerder hebben bekeken:
Badgen biedt een heleboel verschillende opties, dus ik moedig je aan om hun site te bekijken en te spelen! Met een van de sjablonen kunt u bijvoorbeeld het aantal keren weergeven dat een bepaalde GitHub-repo een ster heeft gekregen. Hier is een ster GitHub-badge voor de Next.js-repo als voorbeeld:
https://badgen.net/github/stars/vercel/next.jsBest wel gaaf! Maar wat als u wilt dat uw badge informatie toont die Badgen niet standaard ondersteunt? Gelukkig heeft Badgen een URL-sjabloon waarmee u uw eigen HTTPS-eindpunten kunt gebruiken om gegevens op te halen:
https://badgen.net/https/url/to/your/endpointLaten we bijvoorbeeld zeggen dat we willen dat onze badge de huidige prijs van Bitcoin in USD toont. Het enige dat we nodig hebben, is een aangepast eindpunt dat deze gegevens als JSON retourneert, zoals dit:
{
"color": "blue",
"status": "$39,333.7",
"subject": "Bitcoin Price USD"
}Ervan uitgaande dat ons eindpunt beschikbaar is op https://some-endpoint.example.com/bitcoin, kunnen we de gegevens doorgeven aan Badgen met behulp van het volgende URL-schema:
https://badgen.net/https/some-endpoint.example.com/bitcoin
Nu nog cooler! Maar we moeten nog steeds het eindpunt maken dat de gegevens voor de GitHub-badge levert. 🤔 Dat brengt ons bij...
Badgen + Servet
Er zijn tal van manieren om uw eigen HTTPS-eindpunt te krijgen. Je zou een server kunnen starten met DigitalOcean of AWS EC2, of je zou een serverloze optie kunnen gebruiken zoals Google Cloud Functions of AWS Lambda; deze kunnen echter allemaal nog steeds een beetje ingewikkeld en vervelend worden voor ons eenvoudige gebruik. Daarom stel ik voor In-browser functie-editor van Servet om een eindpunt te coderen en te implementeren zonder enige installatie of configuratie.
Ga naar het voorbeeld van de Bitcoin-badge van Napkin om een voorbeeldeindpunt te zien. U kunt de code zien om de huidige Bitcoin-prijs op te halen en terug te sturen als JSON in de editor. U kunt de code zelf uitvoeren vanuit de editor of rechtstreeks het eindpunt gebruiken.
Om het eindpunt met Badgen te gebruiken, werkt u met hetzelfde URL-schema van hierboven, alleen deze keer met het Napkin-eindpunt:
https://badgen.net/https/napkin-examples.npkn.net/bitcoin-badgeMeer manieren om GitHub-badges aan te passen
Laten we vervolgens gaan vork deze functie zodat we er onze eigen aangepaste code aan kunnen toevoegen. Klik hiervoor op de knop "Fork" in de rechterbovenhoek. U wordt gevraagd een account aan te maken bij Napkin als u nog niet bent aangemeld.
Zodra we de functie met succes hebben geforkt, kunnen we elke gewenste code toevoegen, met behulp van alle npm-modules die we willen. Laten we de . toevoegen Moment.js npm-pakket en werk de eindpuntreactie bij om de tijd weer te geven waarop de prijs van Bitcoin voor het laatst is bijgewerkt, rechtstreeks in onze 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}`
})
}
Het kan je opvallen dat de badge enige tijd nodig heeft om te vernieuwen de volgende keer dat je het README-bestand op GitHub laadt. Dat komt omdat GitHub een proxymechanisme gebruikt om badgeafbeeldingen weer te geven.
GitHub geeft de badge-afbeeldingen op deze manier weer om misbruik te voorkomen, zoals een hoog verzoekvolume of JavaScript-code-injectie. We hebben geen controle over de proxy van GitHub, maar gelukkig cachet het niet te agressief (anders zou dat het doel van badges een beetje teniet doen). In mijn ervaring is de TTL ongeveer 5-10 minuten.
Oké, laatste baas tijd.
Aangepaste SVG-badges met servet
Laten we voor onze laatste truc Napkin gebruiken om een volledig nieuwe SVG terug te sturen, zodat we aangepaste afbeeldingen kunnen gebruiken zoals we zagen in de Next.js-repo.
Een veelvoorkomend gebruik voor GitHub-badges is het weergeven van de huidige status van een website. Laten we dat doen. Dit zijn de twee staten die onze badge ondersteunt:
Badgen ondersteunt geen aangepaste SVG's, dus in plaats daarvan laten we onze badge rechtstreeks met ons Napkin-eindpunt praten. Laten we hiervoor een nieuwe Napkin-functie maken, genaamd site-status-badge.
De code in deze functie doet een verzoek aan: example.com. Als de aanvraagstatus 200 is, wordt de groene badge geretourneerd als een SVG-bestand; anders wordt de rode badge geretourneerd. Jij kan bekijk de functie, maar ik zal de code hier ook ter referentie opnemen:
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'))
}
}De kans is vrij klein dat de example.com site zal ooit uit de lucht gaan, dus ik heb de . toegevoegd forceFail geval om dat scenario te simuleren. Nu kunnen we een . toevoegen /400 na de Napkin-eindpunt-URL om het te proberen:
Heel mooi
En daar hebben we het! Je GitHub-badgetraining is voltooid. Maar de reis is nog lang niet voorbij. Er zijn een miljoen verschillende dingen waar dit soort badges super handig zijn. Veel plezier met experimenteren en laat die README schitteren!
