VitePress NavCards 组件

这是一个用于 VitePress 的卡片式链接导航组件。它能够将普通的 Markdown 列表项自动转换为网格卡片导航，并自动加载或智能生成文字头像。

功能特性

📦 VitePress 原生集成：作为全局 Vue 组件注册，无需在 Markdown 中引入任何额外代码即可直接使用 <NavCards> 标签。
🎨 卡片式布局：利用隐式插槽解析技术，自动将标准的 Markdown 列表转换为自适应宽度的网格卡片。
🌐 多源图标加载与回退：
- 默认加载本地缓存图标，如加载失败（404）会自动降级请求 Google S2 服务或网站根目录的 favicon.ico。
🔠 智能文字头像：
- 支持将 icon-source 设为 text 直接使用文字头像。
- 支持智能算法：中文取前两字，驼峰词/多单词取首字母缩写（如 DeepSeek → DS），单单词取前两个字母（如 Grok → Gr），并使用 HSL 算法哈希出美观的高对比度背景色。
- 终极兜底：即使加载在线图标，如果在线图标全部加载失败，系统也会自动 fallback 渲染出文字头像。
🔄 全局镜像源切换：支持为卡片组配置多个镜像站，并在页面中提供全局快速切换的标签按钮。
🌓 暗黑模式适配：完美融合 VitePress 默认主题的暗黑模式，色彩自动无缝切换。

安装与使用

1. 全局注册组件

组件已在 .vitepress/theme/index.ts 中注册：

typescript

import DefaultTheme from 'vitepress/theme'
import NavCards from './components/NavCards.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('NavCards', NavCards)
  }
}

2. 在 Markdown 中使用

在任何 Markdown 文件中，直接使用 <NavCards> 标签包裹一个普通的链接列表即可：

html

<NavCards>

- [Google](https://www.google.com) - 谷歌搜索引擎
- [GitHub](https://github.com) - 软件项目托管平台

</NavCards>

高级配置项

可以通过在 <NavCards> 标签上添加 Vue Props 属性进行个性化控制：

icon-dir (本地图标目录，默认为 'icons/')
- 支持 当前页面同级路径：若以 ./ 开头（如 icon-dir="./" 或 icon-dir="./icons3d/"），则会自动相对于当前 Markdown 页面所在文件夹进行解析。这非常适合以模块化方式直接将域名图标（如 com.baidu.www.png）存放在 Markdown 文件同级目录下。
- 示例值：_lib/custom-icons/ 或 ./
icon-source (初始图标的加载源，默认为 local)
- 可选值：
  - local : 全局本地图标（如果 icon-dir 设为 ./，则会在当前 Markdown 目录下查找）
  - page : 当前 Markdown 同级目录图标（已可通过 icon-dir="./" 代替）
  - google : 谷歌在线服务
  - site-default : 站点 favicon.ico
  - text : 智能文字头像
icon-failover (第一级降级加载源，默认为 site-default)
- 可选值：与 icon-source 相同 (local | page | google | site-default | text)
mirrors (镜像源列表，用逗号分隔，会在卡片上方生成全局切换按钮)
- 示例值：github.com, github.com.cnpmjs.org

1. 自动获取在线图标 (Google Favicon)

代码写法：

html

<NavCards icon-source="google">

- [Google Gemini](https://gemini.google.com) - 谷歌智能 AI 助手
- [GitHub](https://github.com) - 全球最大的开源软件托管平台
- [DeepSeek](https://www.deepseek.com) - 优秀的国产大语言模型

</NavCards>

实际渲染效果：

2. 智能文字头像 (Text Logo)

当您不想花精力去收集、裁剪或配置网站图标（例如懒得找图，或者某些私有链接没有 Favicon）时，可以使用纯文字头像模式。该模式会自动根据链接标题智能提取极简的文字标识，并自动哈希出美观的高对比度背景色，简单且好看。

代码写法：

html

<NavCards icon-source="text">

- [Google Gemini](https://gemini.google.com) - 提取英文词首字母 GG
- [DeepSeek](https://www.deepseek.com) - 提取驼峰词首字母 DS
- [Grok](https://grok.x.ai) - 单单词提取前两位 Gr
- [小羊笔记](https://github.com) - 中文名称自动提取前两个汉字
- [智谱](https://bigmodel.cn) - 中文词提取

</NavCards>

实际渲染效果：

3. 指定图标目录 (Icon Directory)

通过 data-icon-dir 可以自定义存放域名图标（以 reverseDomain.png 命名的文件）的目录。支持以下两种指定路径：

绝对路径 / 站点根路径：不以 ./ 开头，如 data-icon-dir="icons3d/"（从网站根目录查找）。
相对当前页面路径：以 ./ 开头，表示相对于当前 Markdown 页面所在的同级文件夹，如：
- data-icon-dir="./"：直接读取与当前 Markdown 文件同级目录下的图标。
- data-icon-dir="./icons3d/"：读取 Markdown 同级目录下 icons3d/ 文件夹里的图标（例如 3D 风格图标）。
- data-icon-dir="./iconsFluffy/"：读取 Markdown 同级目录下 iconsFluffy/ 文件夹里的图标（例如毛茸茸风格图标）。

示例 3.1: 相对当前页面同级目录 (data-icon-dir="./")

代码写法：

html

<NavCards icon-dir="./" icon-failover="text">

- [Example](https://example.com) - 演示根据域名自动读取同级目录下的 `com.example.png`
- [Other Domain](https://google.com) : 手动指定同级目录下自定义图片名为 `com.example.png`  ![演示图标](com.example.png)
- [Fallback Text](https://doesnotexist123.com) - 同级目录下无对应图标时，自动降级为文字头像 FT

</NavCards>

实际渲染效果：

示例 3.2: 相对页面路径的子目录（如 3D 风格 ./icons3d/）

代码写法：

html

<NavCards icon-dir="./icons3d/">

- [Vue.js](https://vuejs.org) : 渐进式 JavaScript 框架
- [React](https://react.dev) : 用于构建 Web 和原生交互界面的库
- [Docsify](https://docsify.js.org) : 一个神奇的文档网站生成器
- [TailwindCSS](https://tailwindcss.com) : 无需离开 HTML 即可快速构建网站

</NavCards>

实际渲染效果：

示例 3.3: 相对页面路径的另一个子目录（如毛茸茸风格 ./iconsFluffy/）

代码写法：

html

<NavCards icon-dir="./iconsFluffy/">

- [Vue.js](https://vuejs.org) : 渐进式 JavaScript 框架
- [React](https://react.dev) : 用于构建 Web 和原生交互界面的库
- [Docsify](https://docsify.js.org) : 一个神奇的文档网站生成器
- [TailwindCSS](https://tailwindcss.com) : 无需离开 HTML 即可快速构建网站

</NavCards>

实际渲染效果：

4. 自定义图标

如果您不想使用自动解析域名的 Favicon，可以直接在列表项中插入 Markdown 图片作为自定义卡片图标。支持以下两种写法：

同级目录相对路径：如 com.example.png，自动相对于当前 Markdown 页面文件夹路径解析。
根目录绝对路径：以 / 开头如 /icons3d/org.vuejs.png，自动相对于站点根路径解析。

代码写法：

html

<NavCards>

- [自定义链接](https://example.com) : 这是一个使用当前页面同级目录相对路径图片的卡片  ![自定义图标](com.example.png)
- [Vue.js](https://vuejs.org) : 渐进式 JavaScript 框架（故意指定为 React 3D 图标）  ![](./icons3d/dev.react.png)
- [React](https://react.dev) : 用于构建 Web 和原生交互界面的库（故意指定为 Vue 3D 图标）  ![](./icons3d/org.vuejs.png)

</NavCards>

实际渲染效果：

5. 镜像切换示例

代码写法：

html

<NavCards mirrors="npmjs.com, npmmirror.com">

- [npm Package](https://www.npmjs.com/package/docsify) - 官方包注册地

</NavCards>

实际渲染效果：

镜像源：npmjs.comnpmmirror.com

spring-boot 不同版本文档

html

<NavCards  mirrors="3.5,3.4,3.3">

- [spring-boot 3.5](https://docs.spring.io/spring-boot/3.5/index.html) : Spring Boot

</NavCards>

镜像源：3.53.43.3

Ubuntu LTS Releases 不同的镜像地址

html

<NavCards  mirrors="releases.ubuntu.com/,mirrors.ustc.edu.cn/ubuntu-releases/,mirrors.163.com/ubuntu-releases/,mirrors.huaweicloud.com/ubuntu-releases/,mirrors.aliyun.com/ubuntu-releases/">

- [Ubuntu 24.04 LTS ](https://releases.ubuntu.com/24.04/) : Noble Numbat
- [Ubuntu 22.04 LTS ](https://releases.ubuntu.com/22.04/) : Jammy Jellyfish
- [Ubuntu 20.04 LTS ](https://releases.ubuntu.com/20.04/) : Focal Fossa
- [Ubuntu 18.04 LTS ](https://releases.ubuntu.com/18.04/) : Trusty Tahr

</NavCards>

镜像源：releases.ubuntu.com/mirrors.ustc.edu.cn/ubuntu-releases/mirrors.163.com/ubuntu-releases/mirrors.huaweicloud.com/ubuntu-releases/mirrors.aliyun.com/ubuntu-releases/

VitePress NavCards 组件 ​

功能特性 ​

安装与使用 ​

1. 全局注册组件 ​

2. 在 Markdown 中使用 ​

高级配置项 ​

1. 自动获取在线图标 (Google Favicon) ​

2. 智能文字头像 (Text Logo) ​

3. 指定图标目录 (Icon Directory) ​

4. 自定义图标 ​

5. 镜像切换示例 ​

VitePress NavCards 组件

功能特性

安装与使用

1. 全局注册组件

2. 在 Markdown 中使用

高级配置项

1. 自动获取在线图标 (Google Favicon)

2. 智能文字头像 (Text Logo)

3. 指定图标目录 (Icon Directory)

4. 自定义图标

5. 镜像切换示例