如何为你的 GitHub 项目添加 badge

如何为你的 GitHub 项目添加 badge

我们在很多开源项目的 README 都能看到大量的徽章(badge),这些徽章大都挺漂亮的,最重要的是,通过这些徽章,我们可以快速的获取项目的状态信息,例如:开源协议、版本、单元测试覆盖率等。

那我们应该如何为自己的项目加上一些徽章呢?

markdown 与图片

markdown 插入图片

我们都知道项目的 README 是一个 markdown 文件,在 markdown 内可以这样插入一张图片

1
![](https://cdn.sguan.top/markdown/20200721141223.png)

其效果类似于这样:

markdown 插入图片链接

此外,如果我们想在点击图片后,跳转到某个页面,可以这样写:

1
[![](https://cdn.sguan.top/markdown/20200721141223.png)](https://baidu.com)

其效果类似于这样:

点一下图片试试,看看和前一张图片的区别。

shields.io

徽章其实也只是一些图片,只不过它看起来会很小,包含了一些信息,并且一般是 svg 格式的。也就是说我们只要在 README.md 中引入这种风格的图片就可以了。

一个徽章的构成元素包括:标签、信息、风格样式:

上面这个徽章,它的标签是 RELEASE,信息是 x.x.x 的一个版本号,风格比较扁平化。

问题在于我们如何生成符合自己需求的图片呢?

答案是 shields.io,目前我们在 GitHub 上看到的很多徽章都是在这个网站生成的,该网站提供了数以百计的徽章可以选择,并且你还可以自定义徽章,这足以满意绝大部分开发者的需求。生成的图片都会有一个唯一地址,你可以直接引用该图片,或者下载图片,将其保存到项目中,再通过相对目录引用图片。无论如何,我们需要做的只是生成想要的图片、在 markdown 中引入它。

虽然有很多的徽章可以选择,但一般只需要为重要的信息添加徽章,过多的徽章会让读者无法快速提取其中的信息。至于哪些是重要的信息,这取决于具体的项目以及你自身的理解。

静态徽章

对一个项目来说,某些徽章基本上不会发生变化,例如:开源协议、一些链接等。

这种徽章可以看成是静态徽章,即不会变化的徽章。

开源协议

shields.io 提供了大量的静态徽章,这里我们以 开源协议 系列的徽章为例。

开源协议相关的徽章可以在 这里 看到。

shields 提供的开源协议

点击你需要的协议,然后填入参数(这里我其实没太明白规则,一般填入 e.g. 后面的字符即可),例如:

生成徽章

红色圈出来的部分就是我们生成的徽章,点击下面的 Copy Badge URL 即可复制徽章图片的地址,得到的地址类似于这样:

1
https://img.shields.io/aur/license/android-studio

你也可以点击 展开,复制其它格式的地址,不同格式的地址本质上并没有区别,例如 markdown 格式的徽章地址。

1
![AUR license](https://img.shields.io/aur/license/android-studio)

调整风格

此外,你可以修改参数,生成不同风格的徽章。

style

生成的徽章就会是风格比较扁平化的徽章。

自定义徽章

如果预置的徽章都不能满足你的要求,你还可以生成自定义徽章。

shields.io 每个页面的底部都提供了自定义徽章的功能,你可以根据自己的需要填入信息、生成徽章、引用。

https://img.shields.io/badge/ID-3ks-brightgreen?style=for-the-badge

https://img.shields.io/static/v1?label=NAME&message=Guan&color=brightgreen?style=for-the-badge

https://img.shields.io/static/v1?label=

动态徽章

预置

自定义

参考链接

shields.io

GitHub 项目徽章的添加和设置

如何让你的 GitHub 项目表面上更专业

为你的Github生成漂亮的徽章和进度条

Adding a workflow status badge to your repository

评论