markdown拓展应用

small_Axe
324 阅读5分钟

我们可以通过 markdown 以及一些插件，来丰富我们的readme 文件，或者定制我们GitHub的个人首页。

插入个性化badge

Markdown 里可以使用 HTML 进行高级样式布局。

<div align="center">
  <img src="" />
</div>

通过给外层标签设置align属性，让内容居中。

如果你浏览过一些 GitHub 的开源项目，你一定见过很多 README 文档中都会出现的五颜六色、各式各样的「小牌子」。

Badge

badge 图标均由 shields.io 网站提供。在这个网站上，你只需要提供需要显示的内容，就能得到一个精美的 badge。你还可以自定义样式，可以说非常灵活。我们不仅可以将这些「小牌子」用在 GitHub 里，如果你拥有自己的「个人主页」、「博客」或其他展示个人资料的地方。

Shields.io 的基本用法

简单定制静态badge

Shields.io 就是一个我们开头提到的「牌子渲染服务」。事实上，GitHub 上面大部分「小牌子」都是用 Shields.io 来渲染的。我们可以借助于 Shields.io 服务定制一些个性化的「小牌子」。如下：

<div align='center'>
  <img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d1ab3687b37549e68dac92ae663a34ec~tplv-k3u1fbpfcp-zoom-1.image"/>
  <img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c721cabe7abb4360b55a1e652fbb7a04~tplv-k3u1fbpfcp-zoom-1.image" />
</div>

// 右半边颜色为十六进制代码或者颜色名称
https://img.shields.io/badge/{左半部分标签}-{右半部分标签}-{右半部分颜色}

这样得到的链接是一个 SVG 图片链接，我们可以直接用插入图片的语法规则加到我们的 Markdown 文本文件中或 HTML 里面。

实时更新的badge

我们前面生成的badge是静态的，其中的文本是固定不变的，只能做一些好看的标识。而shields.io 完全支持动态的数据显示，比如粉丝，关注着数量，RSS订阅者数量等...

如果我们要显示一些动态的数据，那么我们需要一些受支持的数据接口，这样我们的shields.iobadge服务器就会先从这一数据接口请求相应的动态数据，并按照请求的结果进行渲染。

虽然 Shields.io 服务 API 的功能非常完善，能够支持许多第三方 API 节点的数据服务，但是有一些服务：

  • API 接口返回复杂，无法直接用 Shields.io 简单处理
  • API 访问缓慢、不稳定，经常出现超时或无法访问的情况
  • 访问一些数据需要进行认证，直接访问会返回 403 无权限
  • 直接不对外公开 API 接口，没有面向开发者的开放平台，无法直接请求数据

当我们想要显示这些平台的关注者数量，粉丝数量时往往力不从心。这时候我们就可以结合SubStats，这是一个致力于提供社交帐号粉丝数统计服务的开源项目，你只需要按照指定格式要求，就能从他们的开放接口获得你在某个平台的粉丝数量。然后在 shields.io 的 Dynamic 部分，提供固定格式的查询信息，就能 将动态查询到的数据与 badges 结合起来使用。

Substats

下面我来简单介绍一下如何利用 Substats 配合 Shields.io 定制 badge：

用 Substats 配合 Shields.io 制作动态badge

Substats 是一个非常方便易用的请求订阅者、粉丝、关注用户数量 API 服务。目前，Substats 平台支持了包括 Feedly、GitHub、Twitter、知乎和少数派在内的五个平台和网站。Substats 将复杂的原平台 API 请求进行了隐藏、简化和集成，让用 Substats 的你只需要关注两个参数：平台名称、用户名称，一波访问，即可得到对应的关注数量。

通过 Substats API 获取我们期望的数据

为了更好的配合 Shields.io 服务，将 Substats 的 API 设计成简单拼接 URL 即可进行数据请求。Substats API 的语法非常简单，我们只需要关注并提供如下的两个字段即可进行请求：

  • :sound: 目标服务名称 source：你所想要请求的服务、网站和平台名（比如：sspai、weibo……）
  • :video_game: 请求数据标签 queryKey：在这一服务中查询的关注数据对应的标签或名称.

这样，我们就可以用这样的语法来拼接一个 URL（注意第一个字符是 ?，其他用 & 拼接）：

单个平台请求
https://api.spencerwoo.com/substats/?source={目标服务名称}&queryKey={请求数据标签}

这一 URL 会给我们返回类似下面的 JSON 结果：

{
  "status": 200,
  "data": {
    "totalSubs": 3,
    "subsInEachSource": {
    	"github": 3
  	},
  	"failedSources": {}
  }
}

我们可以这样理解返回的数据：

  • :game_die: status 表示请求是否成功，成功即200
  • :house_with_garden: data 请求返回的数据：totalSubs 表示总关注数，subsInEachSource 表示每个服务请求到的粉丝数据， failedSources 表示请求失败的数据源。

我们所需要的字段即为 $.data.totalSubs, 也就是3，表示我们GitHub的关注人数。

多个平台串联请求

我们可以用 | 串联多个请求。比如，我同时请求知乎、GitHub 两个平台上面的关注，即可这样构造请求（多个 source 和 queryKey 组合按照顺序进行请求即可，顺序在请求过程中不会丢失）：

https://api.spencerwoo.com/substats/?source=zhihu&queryKey=xx&source=github&queryKey=xx

{
  "status": 200,
  "data": {
    "totalSubs": 314,
    "subsInEachSource": {
      "zhihu": 100,
      "github": 214
    },
    "failedSources": {}
  }
}

GitHub仓库卡片和分析统计

仓库卡片

开源项目：github-profile-trophy

https://github-profile-trophy.vercel.app/?username={USERNAME}&title=Stars,Followers

kapian

分析统计

开源项目： github-readme-stats

https://github-readme-stats.vercel.app/api?username={用户名}&show_icons=true

以上两个库都可以修改主题或者样式，具体参数可以跳转到GitHub 去看。

github阅读数统计

开源项目： GitHub Profile Views Counter

https://komarev.com/ghpvc/?username={your-github-username}

我的博客

avatar
文章
阅读
粉丝