Menambah lencana github tersuai ke repo anda

Sekiranya anda telah meluangkan masa untuk melihat repos sumber terbuka, anda mungkin menyedari bahawa kebanyakan mereka menggunakan lencana dalam fail readme mereka. Menggabungkan repositori React Rasmi, contohnya. Terdapat lencana GitHub di seluruh thereadmunice yang berkomunikasi info dinamik yang penting, seperti versi terkini yang dikeluarkan dan sama ada membina semasa.

Lencana seperti ini memberikan cara yang baik untuk menyerlahkan maklumat penting mengenai repositori. Anda juga boleh menggunakan aset tersuai anda sendiri sebagai lencana, seperti Next.js dalam repo.

Tetapi perkara yang paling berguna mengenai lencana GitHub setakat ini ialah mereka mengemas kini dengan sendirinya . Daripada nilai hardcoding ke dalam ReadMe anda, lencana di GitHub secara automatik boleh mengambil perubahan dari pelayan jauh.

Mari kita bincangkan cara menambah lencana GitHub dinamik ke fail ReadMe projek anda sendiri. Kami akan mulakan dengan menggunakan penjana dalam talian yang dipanggil Badgen.net untuk membuat beberapa lencana asas. Kemudian kami akan membuat lencana kami dinamik dengan mengaitkannya dengan fungsi tanpa pelayan kami melalui serbet. Akhirnya, kami akan mengambil satu langkah lebih jauh dengan menggunakan fail SVG tersuai kami sendiri.

Pertama: Bagaimana lencana berfungsi?

Sebelum kita mula membina beberapa lencana di GitHub, mari kita cepat lakukan bagaimana ia dilaksanakan. Ia sebenarnya sangat mudah: lencana hanya imej . Fail ReadMe ditulis dalam markdown, dan Markdown menyokong imej seperti SO:

 ! \ [alt text \] (jalan atau url ke imej)

Hakikat bahawa kita boleh memasukkan URL ke imej bermakna halaman markdown akan meminta data imej dari pelayan apabila halaman tersebut diberikan. Jadi, jika kita mengawal pelayan yang mempunyai imej, kita boleh mengubah imej apa yang dihantar kembali menggunakan logik apa sahaja yang kita mahu!

Syukurlah, kami mempunyai beberapa pilihan untuk menggunakan logik pelayan kami sendiri tanpa keseluruhan "menyediakan bahagian pelayan". Untuk kes penggunaan asas, kami boleh membuat imej lencana GitHub kami dengan badgen.net menggunakan templat yang telah ditetapkan. Dan sekali lagi, serbet akan membolehkan kami dengan cepat mengodkan fungsi tanpa pelayan dalam penyemak imbas kami dan kemudian menggunakannya sebagai titik akhir bahawa lencana GitHub kami boleh bercakap dengannya.

Membuat lencana dengan badgen

Mari kita mulakan dengan penyelesaian lencana yang paling mudah: lencana statik melalui badgen.net. API Badgen menggunakan corak URL untuk membuat lencana templat dengan cepat. Corak URL adalah seperti berikut:

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

Terdapat senarai lengkap pilihan yang anda ada untuk warna, ikon, dan banyak lagi pada badgen.net. Untuk contoh ini, mari kita gunakan nilai -nilai ini:

• : Subjek: Helo
• : Status :: dunia
• : Warna :: merah
• : Ikon :: Twitter

URL terakhir kami kelihatan seperti ini:

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

Lihat gambar

Menambah lencana github ke fail readme

Sekarang kita perlu membenamkan lencana ini dalam fail readme repo GitHub kami. Kita boleh melakukannya di Markdown menggunakan sintaks yang kita lihat sebelumnya:

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

Badgen menyediakan satu ton pilihan yang berbeza, jadi saya menggalakkan anda untuk menyemak laman web mereka dan bermain -main! Sebagai contoh, salah satu daripada templat membolehkan anda menunjukkan bilangan kali repo GitHub yang diberikan telah dibintangi. Berikut adalah lencana github bintang untuk repo seterusnya.js sebagai contoh:

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

Lihat gambar

Cukup keren! Tetapi bagaimana jika anda mahu lencana anda menunjukkan beberapa maklumat bahawa Badgen tidak menyokong secara asli? Nasib baik, Badgen mempunyai templat URL untuk menggunakan titik akhir HTTPS anda sendiri untuk mendapatkan data:

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

Sebagai contoh, katakan kami mahu lencana kami menunjukkan harga semasa Bitcoin dalam USD. Apa yang kita perlukan adalah titik akhir tersuai yang mengembalikan data ini sebagai JSON seperti ini:

 {
  "warna": "biru",
  "Status": "$ 39,333.7",
  "Subjek": "Harga Bitcoin USD"
}

Dengan mengandaikan titik akhir kami boleh didapati di https://some-endpoint.example.com/bitcoin, kami boleh lulus datanya ke Badgen menggunakan skema URL berikut:

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

Malah lebih sejuk sekarang! Tetapi kita masih perlu membuat titik akhir yang menyediakan data untuk lencana GitHub. ? Yang membawa kita ke…

Napkin Badgen

Terdapat banyak cara untuk mendapatkan titik akhir HTTPS anda sendiri. Anda boleh berputar pelayan dengan DigitalOcean atau AWS EC2, atau anda boleh menggunakan pilihan tanpa pelayan seperti Google Cloud Fungsi atau AWS Lambda; Walau bagaimanapun, semuanya masih boleh menjadi agak kompleks dan membosankan untuk kes penggunaan mudah kami. Itulah sebabnya saya mencadangkan editor fungsi dalam pelayar serbet untuk kod dan menggunakan titik akhir tanpa sebarang pemasangan atau konfigurasi.

Kepala ke Bitcoin Badge Contoh Contoh untuk melihat contoh endpoint. Anda dapat melihat kod untuk mendapatkan harga bitcoin semasa dan mengembalikannya sebagai JSON dalam editor. Anda boleh menjalankan kod sendiri dari editor atau menggunakan titik akhir secara langsung.

Untuk menggunakan titik akhir dengan badgen, bekerjasama dengan skema URL yang sama dari atas, hanya kali ini dengan titik akhir serbet:

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

Lihat gambar

Lebih banyak cara untuk menyesuaikan lencana github

Seterusnya, mari garpu fungsi ini supaya kita dapat menambah kod tersuai kita sendiri. Klik butang "Fork" di bahagian atas kanan untuk berbuat demikian. Anda akan diminta membuat akaun dengan serbet jika anda belum mendaftar masuk.

Sebaik sahaja kami berjaya melancarkan fungsi ini, kami boleh menambah apa sahaja kod yang kami mahu, menggunakan mana -mana modul NPM yang kami mahukan. Mari Tambahkan Pakej NPM Moment.js dan Kemas kini tindak balas Endpoint untuk menunjukkan masa bahawa harga bitcoin terakhir dikemas kini secara langsung dalam lencana GitHub kami:

 Import Ambil dari 'Node-Fetch'
momen import dari 'momen'

const bitcoinprice = async () => {
  const res = menunggu pengambilan ("<https:>")
  const json = menunggu res.json ()
  const lastPrice = json.usd.last ""

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

  kembali ints.slice (0, -3) "," ints.slice (-3) "." perpuluhan
}

Eksport lalai async (req, res) => {
  const btc = tunggu bitcoinprice ()

  res.json ({
    Ikon: 'Bitcoin',
    Subjek: `harga bitcoin usd ($ {momen (). format ('h: mma')})`,
    Warna: 'biru',
    Status: `\\ $$ {BTC}`
  })
}</https:>

Anda mungkin melihat bahawa lencana mengambil sedikit masa untuk menyegarkan semula pada kali berikutnya anda memuatkan fail ReadMe di GitHub. Itu kerana GitHub menggunakan mekanisme proksi untuk melayani imej lencana.

GitHub melayani imej lencana dengan cara ini untuk mengelakkan penyalahgunaan, seperti jumlah permintaan tinggi atau suntikan kod JavaScript. Kami tidak dapat mengawal proksi GitHub, tetapi mujurlah, ia tidak terlalu agresif (atau yang lain akan mengalahkan tujuan lencana). Dalam pengalaman saya, TTL adalah sekitar 5-10 minit.

Ok, masa bos terakhir.

Lencana SVG tersuai dengan serbet

Untuk helah terakhir kami, mari kita gunakan serbet untuk menghantar semula SVG yang baru, jadi kami boleh menggunakan imej tersuai seperti yang kita lihat pada repo seterusnya.

Kes penggunaan biasa untuk lencana GitHub menunjukkan status semasa untuk laman web. Mari buat begitu. Berikut adalah dua negeri lencana kami akan menyokong:

Badgen tidak menyokong SVGs adat, jadi sebaliknya, kami akan bercakap lencana terus ke titik akhir serbet kami. Mari kita buat fungsi serbet baru untuk ini yang dipanggil Status-Badge.

Kod dalam fungsi ini membuat permintaan untuk contoh.com. Jika status permintaan adalah 200, ia mengembalikan lencana hijau sebagai fail SVG; Jika tidak, ia mengembalikan lencana merah. Anda boleh menyemak fungsi tersebut, tetapi saya juga akan memasukkan kod di sini untuk rujukan:

 Import Ambil dari 'Node-Fetch'

const site_url = "<https:>"

// svg penuh di <https:>
const customupbadge = ''
const customdownbadge = ''

const isSiteup = async () => {
  const res = menunggu pengambilan (site_url)
  kembali res.ok
}

Eksport lalai async (req, res) => {
  const forcefail = req.path? .endswith ('/400')

  const sihat = menunggu isiteup ()
  res.set ('kandungan-jenis', 'imej/svg xml')
  jika (sihat &&! forcefail) {
    res.send (buffer.from (customupBadge) .toString ('base64'))
  } else {
    res.send (buffer.from (customdownbadge) .toString ('base64'))
  }
}</https:></https:>

Odds cukup rendah bahawa laman Example.com akan turun, jadi saya menambah kes Forcefail untuk mensimulasikan senario itu. Sekarang kita boleh menambah A /400 selepas URL Endpoint Napkin untuk mencubanya:

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

Lihat status lencana lencana status ke bawah lencana

Sangat bagus?

Dan di sana kita memilikinya! Latihan lencana github anda selesai. Tetapi perjalanan itu jauh dari. Terdapat satu juta perkara yang berbeza di mana lencana seperti ini sangat membantu. Bersenang -senang bereksperimen dan pergi membuat readme berkilau! ✨

Atas ialah kandungan terperinci Menambah lencana github tersuai ke repo anda. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!