登录
开源一个 markdown-it 插件：让你的博客支持 GitHub 用户悬浮卡片
2026年1月24日 18:20
开源一个 markdown-it 插件：让你的博客支持 GitHub 用户悬浮卡片
前言
在写技术博客或文档时，我们经常需要提到 GitHub 上的开发者，比如「这个方案参考了 @antfu 的实现」。但读者看到这个 @ 时，往往需要点击跳转才能了解这个人是谁。
能不能像 GitHub 那样，鼠标悬停就能看到用户信息呢？
于是我开发了这个插件：markdown-it-github-mention-card
效果预览
在 Markdown 中写入：
这个项目的灵感来自 {@antfu} 的开源作品。
渲染后，鼠标悬停在链接上，就会出现一个精美的用户信息卡片，包含：
- 用户头像
- 用户名和简介
- 地理位置、公司信息
- 粉丝数、关注数、公开仓库数
无需跳转页面，信息一目了然。
特性
-
语法简洁：
{@username}即可，支持自定义显示文本 - 悬浮卡片：调用 GitHub API 实时获取用户信息
-
暗色模式：自动适配
.dark主题类 - SSR/SSG 友好：完美支持 VitePress、Nuxt、Next.js 等框架
- TypeScript：完整的类型定义
- 轻量无依赖：核心代码仅依赖 markdown-it
安装
# npm
npm install markdown-it-github-mention-card
# pnpm
pnpm add markdown-it-github-mention-card
# yarn
yarn add markdown-it-github-mention-card
基础使用
import MarkdownIt from 'markdown-it'
import MarkdownItGitHubMentionCard, { initHoverCard } from 'markdown-it-github-mention-card'
const md = new MarkdownIt()
md.use(MarkdownItGitHubMentionCard, {
// 可选：提高 GitHub API 速率限制
githubToken: 'YOUR_GITHUB_TOKEN',
})
// 渲染 Markdown
const html = md.render('{@antfu} 是 Vue 核心团队成员')
document.querySelector('#app').innerHTML = html
// 初始化悬浮卡片（浏览器端调用）
initHoverCard()
语法说明
插件支持三种写法：
| 语法 | 说明 | 示例 |
|---|---|---|
{@username} |
基础用法 |
{@antfu} → 显示 "antfu" |
{@username|显示文本} |
自定义文本 |
{@antfu|Anthony Fu} → 显示 "Anthony Fu" |
{@username|显示文本|链接} |
自定义链接 | {@antfu|博客|https://antfu.me} |
SSR/SSG 场景最佳实践
在服务端渲染场景下，构建时和浏览器端环境分离，推荐以下方式：
服务端（构建时）：
import MarkdownIt from 'markdown-it'
import MarkdownItGitHubMentionCard from 'markdown-it-github-mention-card'
const md = new MarkdownIt()
md.use(MarkdownItGitHubMentionCard)
// 服务端不传 token，避免暴露
const html = md.render('{@antfu}')
客户端（浏览器）：
import { initHoverCard } from 'markdown-it-github-mention-card'
// VitePress / Vite
initHoverCard(import.meta.env.VITE_GITHUB_TOKEN)
// Next.js
initHoverCard(process.env.NEXT_PUBLIC_GITHUB_TOKEN)
暗色模式
插件内置暗色模式支持，当页面或父元素包含 .dark 类时，卡片自动切换暗色主题：
<html class="dark">
<!-- 卡片自动适配暗色 -->
</html>
与 VitePress、Tailwind CSS 等主流方案完美兼容。
在 VitePress 中使用
// .vitepress/config.ts
import MarkdownItGitHubMentionCard from 'markdown-it-github-mention-card'
export default {
markdown: {
config: (md) => {
md.use(MarkdownItGitHubMentionCard)
}
}
}
// .vitepress/theme/index.ts
import { initHoverCard } from 'markdown-it-github-mention-card'
import { onMounted } from 'vue'
export default {
enhanceApp() {
if (typeof window !== 'undefined') {
onMounted(() => {
initHoverCard(import.meta.env.VITE_GITHUB_TOKEN)
})
}
}
}
实现原理
简单介绍一下核心实现：
-
Markdown 解析：通过 markdown-it 的 inline rule，匹配
{@...}语法，生成带有data-github-user属性的<a>标签 -
悬浮卡片：
initHoverCard()在浏览器端监听鼠标事件，当悬停在目标链接上时：- 调用 GitHub REST API 获取用户信息
- 动态创建卡片 DOM 并定位显示
- 内置请求缓存，避免重复请求
-
样式注入：首次调用时自动注入 CSS，支持亮/暗两套主题
为什么不用 GitHub 官方的 Hover Card？
GitHub 的 Hover Card 仅在 github.com 域名下生效，且需要登录状态。本插件：
- 可在任意网站使用
- 无需用户登录 GitHub
- 可自定义样式和行为
- 适配各种 SSR/SSG 框架
项目地址
写在最后
这是我开源的一个小工具，希望能帮助到有类似需求的同学。
如果觉得有用，欢迎：
- 给项目点个 ⭐ Star
- 提 Issue 反馈问题或建议
- 提 PR 一起完善
有任何问题欢迎在评论区交流讨论！
