❌

阅读视图

发现新文章，点击刷新页面。

开源一个 markdown-it 插件：让你的博客支持 GitHub 用户悬浮卡片

✇掘金 前端
Joie

开源一个 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)
      })
    }
  }
}

实现原理

简单介绍一下核心实现：

  1. Markdown 解析：通过 markdown-it 的 inline rule，匹配 {@...} 语法，生成带有 data-github-user 属性的 <a> 标签

  2. 悬浮卡片：initHoverCard() 在浏览器端监听鼠标事件，当悬停在目标链接上时：

    • 调用 GitHub REST API 获取用户信息
    • 动态创建卡片 DOM 并定位显示
    • 内置请求缓存，避免重复请求

  3. 样式注入：首次调用时自动注入 CSS，支持亮/暗两套主题

为什么不用 GitHub 官方的 Hover Card？

GitHub 的 Hover Card 仅在 github.com 域名下生效，且需要登录状态。本插件：

  • 可在任意网站使用
  • 无需用户登录 GitHub
  • 可自定义样式和行为
  • 适配各种 SSR/SSG 框架

项目地址

写在最后

这是我开源的一个小工具，希望能帮助到有类似需求的同学。

如果觉得有用，欢迎：

  • 给项目点个 ⭐ Star
  • 提 Issue 反馈问题或建议
  • 提 PR 一起完善

有任何问题欢迎在评论区交流讨论！

❌