Ajouter des badges GitHub personnalisés à votre référentiel

Si vous avez passé du temps à regarder des références open source ONGITHUB, vous avez probablement remarqué que la plupart d'entre eux utilisent des badges dans leurs fichiers ReadMe. Take le référentiel de réaction officielle, par exemple. Il y a des badges GitHub partout dans le fait que la construction actuelle passe.

Des badges comme ceux-ci offrent un bon moyen de mettre en évidence des informations clés sur un référentiel. Vous pouvez même utiliser vos propres actifs personnalisés comme badges, comme Next.js dans son dépôt.

Mais la chose la plus utile à propos des badges GitHub est de loin qu'ils se mettent à jour par eux-mêmes . Au lieu de coder en dur dans votre lecture, les badges dans GitHub peuvent automatiquement récupérer des modifications à partir d'un serveur distant.

Discutons de la façon d'ajouter des badges GitHub dynamiques au fichier ReadMe de votre propre projet. Nous commencerons par utiliser un générateur en ligne appelé badgen.net pour créer des badges de base. Ensuite, nous rendrons nos badges dynamiques en les connectant à notre propre fonction sans serveur via la serviette. Enfin, nous allons aller plus loin en utilisant nos propres fichiers SVG personnalisés.

Tout d'abord: comment fonctionnent les badges?

Avant de commencer à construire des badges dans Github, passons rapidement à la façon dont ils sont mis en œuvre. C'est en fait très simple: les badges ne sont que des images . Les fichiers ReadMe sont écrits dans Markdown, et Markdown prend en charge des images comme ainsi:

 ! \ [Texte alt \] (chemin ou URL à l'image)

Le fait que nous puissions inclure une URL sur une image signifie qu'une page de démarrage demandera les données de l'image à un serveur lorsque la page sera rendue. Donc, si nous contrôlons le serveur qui a l'image, nous pouvons modifier l'image renvoyée en utilisant la logique que nous voulons!

Heureusement, nous avons quelques options pour déployer notre propre logique de serveur sans la partie «configurer le serveur». Pour les cas d'utilisation de base, nous pouvons créer nos images de badge GitHub avec Badgen.net en utilisant ses modèles prédéfinis. Et encore une fois, la serviette nous permettra de coder rapidement une fonction sans serveur dans notre navigateur, puis le déploie comme un point de terminaison avec lequel nos badges GitHub peuvent parler.

Faire des badges avec Badgen

Commençons par la solution de badge la plus simple: un badge statique via badgen.net. L'API BADGEN utilise des modèles d'URL pour créer des badges modèles à la volée. Le modèle URL est le suivant:

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

Il existe une liste complète des options que vous avez pour les couleurs, les icônes et plus encore sur Badgen.net. Pour cet exemple, utilisons ces valeurs:

• : Sujet: Bonjour
• : Statut :: Monde
• : Couleur :: Rouge
• : icône :: Twitter

Notre URL finale finit par ressembler à ceci:

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

Afficher l'image

Ajout d'un badge GitHub au fichier ReadMe

Maintenant, nous devons intégrer ce badge dans le fichier ReadMe de notre dépôt GitHub. Nous pouvons le faire dans Markdown en utilisant la syntaxe que nous avons examinée plus tôt:

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

Badgen offre une tonne d'options différentes, donc je vous encourage à consulter leur site et à jouer! Par exemple, l'un des modèles vous permet de montrer le nombre de fois qu'un repo GitHub donné a été joué. Voici un badge Star Github pour le repo suivant.js comme exemple:

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

Afficher l'image

Assez cool! Mais que se passe-t-il si vous voulez que votre badge montre des informations que Badgen ne supporte pas nativement? Heureusement, Badgen a un modèle URL pour utiliser vos propres points de terminaison HTTPS pour obtenir des données:

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

Par exemple, disons que nous voulons que notre badge montre le prix actuel du Bitcoin en USD. Tout ce dont nous avons besoin est un point de terminaison personnalisé qui renvoie ces données comme JSON comme ceci:

 {
  "couleur": "bleu",
  "Statut": "39 333,7 $",
  "Sujet": "Bitcoin Price USD"
}

En supposant que notre point de terminaison est disponible sur https://some-endpoint.example.com/bitcoin, nous pouvons transmettre ses données à Badgen en utilisant le schéma URL suivant:

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

Même plus cool maintenant! Mais nous devons encore créer le point de terminaison qui fournit les données pour l'insigne GitHub. ? Ce qui nous amène à…

Serviette Badgen

Il existe de nombreuses façons d'obtenir votre propre point de terminaison HTTPS. Vous pouvez faire tourner un serveur avec DigitalOcean ou AWS EC2, ou vous pouvez utiliser une option sans serveur comme Google Cloud Functions ou AWS Lambda; Cependant, ceux-ci peuvent tous devenir un peu complexes et fastidieux pour notre cas d'utilisation simple. C'est pourquoi je suggère que l'éditeur de fonction de navigateur de Napkin pour coder et déployer un point de terminaison sans aucune installation ni configuration.

Rendez-vous à l'exemple de badge Bitcoin de Naperkin pour voir un exemple de point de terminaison. Vous pouvez voir le code pour récupérer le prix Bitcoin actuel et le retourner en JSON dans l'éditeur. Vous pouvez exécuter le code vous-même à partir de l'éditeur ou utiliser directement le point de terminaison.

Pour utiliser le point de terminaison avec Badgen, travaillez avec le même schéma d'URL d'en haut, seulement cette fois avec le point de terminaison de la serviette:

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

Afficher l'image

Plus de façons de personnaliser les badges GitHub

Ensuite, fournissons cette fonction afin que nous puissions y ajouter notre propre code personnalisé. Cliquez sur le bouton «Fork» en haut à droite pour le faire. Vous serez invité à créer un compte avec une serviette si vous n'êtes pas déjà connecté.

Une fois que nous avons réussi à nourrir la fonction, nous pouvons ajouter le code que nous voulons, en utilisant tous les modules NPM que nous voulons. Ajoutons le package NPM Moment.js et mettons à jour la réponse de point de terminaison pour afficher l'heure que le prix de Bitcoin a été mis à jour pour la dernière fois dans notre badge GitHub:

 Importer Fetch à partir de «nœud-fetch»
Importer un moment du «moment»

const bitcoinprice = async () => {
  const res = attendre fetch ("<https:>")
  const Json = attendre res.json ()
  const lastprice = json.usd.last ""

  const [ints, décimales] = lastprice.split (".")

  return ints.slice (0, -3) "," ints.slice (-3) "." décimales
}

Exporter Async par défaut (req, res) => {
  const btc = attendre bitcoinprice ()

  res.json ({
    Icône: 'Bitcoin',
    Sujet: `Bitcoin Prix USD ($ {Moment (). Format ('H: MMA')})`,
    couleur: «bleu»,
    statut: `\\ $$ {btc}`
  })
}</https:>

Vous remarquerez peut-être que le badge prend un peu de temps pour actualiser la prochaine fois que vous chargerez le fichier ReadMe sur GitHub. C'est parce que GitHub utilise un mécanisme proxy pour servir les images de badge.

GitHub sert les images de badge de cette façon pour prévenir les abus, comme un volume de demande élevé ou une injection de code JavaScript. Nous ne pouvons pas contrôler le proxy de Github, mais heureusement, il ne se cache pas trop agressivement (sinon cela vaincrait en quelque sorte le but des badges). D'après mon expérience, le TTL est d'environ 5 à 10 minutes.

Ok, temps final du boss.

Badges SVG personnalisés avec serviette

Pour notre dernier astuce, utilisons une serviette pour renvoyer un tout nouveau SVG, afin que nous puissions utiliser des images personnalisées comme nous l'avons vu sur le repo suivant.js.

Un cas d'utilisation courant pour les badges GitHub affiche l'état actuel d'un site Web. Faisons ça. Voici les deux États que notre badge soutiendra:

Badgen ne prend pas en charge les SVG personnalisés, donc à la place, nous aurons notre badge parler directement à notre point de terminaison de serviette. Créons une nouvelle fonction de serviette pour ce site appelé Site-Status-Badge.

Le code de cette fonction fait une demande à example.com. Si l'état de la demande est de 200, il renvoie l'insigne vert en tant que fichier SVG; Sinon, il renvoie l'insigne rouge. Vous pouvez consulter la fonction, mais j'inclurai également le code ici pour référence:

 Importer Fetch à partir de «nœud-fetch»

const Site_url = "<https:>"

// SVG complet à <https:>
const customupbadge = ''
const CustomdownBadge = ''

const issiteup = async () => {
  const Res = attendre fetch (site_url)
  return res.ok
}

Exporter Async par défaut (req, res) => {
  constancefail = req.path? .endSwith ('/ 400')

  const Healthy = Await ISSITEUP ()
  res.set («contenu-type», «image / svg xml»)
  if (Healthy &&! ForceFail) {
    res.send (buffer.from (CustomUpBadge) .ToString ('Base64'))
  } autre {
    res.send (buffer.from (CustomdownBadge) .ToString ('Base64'))
  }
}</https:></https:>

Les chances sont assez faibles que le site Exemple.com baisse jamais, j'ai donc ajouté le cas de ForceFail pour simuler ce scénario. Maintenant, nous pouvons ajouter A / 400 après l'URL de point de terminaison de la serviette pour l'essayer:

 ! \ [Status Up \] (https://napkin-examples.npkn.net/site-status-badge/)
! \ [Status Down \] (https://napkin-examples.npkn.net/site-status-badge/400)

Afficher l'état de l'insigne de l'insigne de l'état du statut vers le bas

Très agréable ?

Et là, nous l'avons! Votre formation de badge GitHub est terminée. Mais le voyage est loin d'être terminé. Il y a un million de choses différentes où des badges comme celui-ci sont super utiles. Amusez-vous à expérimenter et allez faire de cette étincelle réadme! ✨

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!