友链配置

ShokaX 主题内置友链页面，支持卡片式展示、站点预览图、自定义主题色等特性。

快速开始

1. 添加第一个友链

打开 src/theme.config.ts，在 friends.links 中添加友链信息：

src/theme.config.ts

export default defineConfig({
  // ...其他配置
  friends: {
    title: "友链",
    description: "卡片式展示,支持站点预览与主题色点缀。",
    links: [
      {
        url: "https://example.com/",
        title: "示例站点",
        desc: "站点简介,一句话描述",
        author: "作者名",
        avatar: "https://example.com/avatar.png",
      },
    ],
  },
});

2. 访问友链页面

保存后访问 /friends/ 即可看到友链卡片。

必填字段

每个友链卡片需要 5 个必填字段：url、title、desc、author、avatar。

基础配置

页面标题与描述

src/theme.config.ts

friends: {
  title: "友链",           // 友链页标题
  description: "我的伙伴们",  // 友链页描述（显示在标题下方）
  links: [
    // 友链列表...
  ],
}

友链列表

links 是数组，每个友链对象包含以下字段：

字段	类型	必填	说明
url	string	✅	站点链接
title	string	✅	站点标题
desc	string	✅	站点简介
author	string	✅	作者名
avatar	string	✅	头像 URL
color	string	❌	主题色（CSS 颜色值）
siteImage	string	❌	站点预览图 URL

示例：

src/theme.config.ts

links: [
  {
    url: "https://astro.build/",
    title: "Astro",
    desc: "静态站点框架,体验轻快",
    author: "Astro Team",
    avatar: "https://avatars.githubusercontent.com/u/44914786?s=200",
  },
  {
    url: "https://svelte.dev/",
    title: "Svelte",
    desc: "编译时框架,写起来很顺手",
    author: "Svelte Team",
    avatar: "https://avatars.githubusercontent.com/u/23617963?s=200",
    color: "var(--color-red)",  // 自定义主题色
  },
]

进阶特性

自定义主题色

每个友链卡片可以设置独特的主题色（用于卡片强调色）：

src/theme.config.ts

{
  url: "https://example.com/",
  title: "示例站点",
  // ...其他字段
  color: "var(--color-pink)",  // 使用主题预设颜色
  // 或
  color: "#ff6b9d",            // 使用自定义颜色值
}

主题预设颜色：

• var(--color-red) - 红色
• var(--color-orange) - 橙色
• var(--color-yellow) - 黄色
• var(--color-green) - 绿色
• var(--color-blue) - 蓝色
• var(--color-pink) - 粉色

注意

如果不指定 color，默认使用蓝色（var(--color-blue)）。

站点预览图

添加 siteImage 字段可显示站点预览图（鼠标悬停时显示”访问站点”遮罩）：

src/theme.config.ts

{
  url: "https://bun.sh/",
  title: "Bun",
  desc: "一体化 JavaScript 运行时",
  author: "Bun Team",
  avatar: "https://avatars.githubusercontent.com/u/108928776?s=200",
  siteImage: "https://bun.sh/logo.svg",  // 站点预览图
  color: "var(--color-green)",
}

预览图来源建议：

• 站点 logo/banner
• 站点首屏截图
• 代表性配图

图片要求：

• 推荐宽高比 16:9 或 2:1
• 建议宽度不低于 800px（保证清晰度）
• 文件格式：JPG/PNG/WebP/AVIF/SVG

本站友链信息配置

如果你希望其他站点添加本站时使用统一的友链信息，可以配置以下字段：

src/theme.config.ts

friends: {
  title: "友链",
  description: "我的伙伴们",
  // 本站友链信息（生成友链配置示例）
  avatar: "https://example.com/my-avatar.png",
  color: "var(--color-pink)",
  siteImage: "https://example.com/preview.png",
  links: [
    // 友链列表...
  ],
}

配置后，友链页面会显示友链配置示例 JSON 代码块，方便其他站长复制：

{
  "url": "https://yoursite.com/",
  "title": "ShokaX",
  "desc": "A brief introduction",
  "author": "Your Name",
  "avatar": "https://example.com/my-avatar.png",
  "color": "var(--color-pink)",
  "siteImage": "https://example.com/preview.png"
}

自动填充

url、title、desc、author 会从其他配置自动获取：

• url：从 astro.config.mjs 的 site 字段获取
• title：从 brand.title 或 siteName 获取
• desc：从 sidebar.description 获取
• author：从 sidebar.author 获取

自定义友链规则

友链规则显示在友链页面顶部，用于说明友链申请要求。

修改规则内容

编辑 src/content/friends-rules.md：

src/content/friends-rules.md

---
title: 友链规则
---

欢迎交换友链！请在提交前确认以下事项：

- **内容健康**：站点内容合规，不含违法/侵权/恶意信息。
- **稳定可访问**：站点可稳定访问，避免频繁跳转或长时间不可用。
- **原创优先**：以原创或高质量内容为主，拒绝采集站。
- **互链友好**：请在贵站添加本站友链后再提交。

支持 Markdown

friends-rules.md 支持完整 Markdown 语法，可以添加列表、链接、强调等格式。

添加更多规则

可以自由扩展规则内容，例如：

src/content/friends-rules.md

---
title: 友链规则
---

## 申请要求

- 站点正常运行超过 3 个月
- 有至少 10 篇原创文章
- 加入本站友链后再提交

## 申请方式

请在评论区或通过 [邮件](mailto:your@email.com) 提交以下信息：

- 站点名称
- 站点链接
- 站点简介
- 头像 URL

## 友链移除规则

以下情况可能移除友链：

- 站点长期（超过 1 个月）无法访问
- 站点内容违规或含恶意代码
- 单方面移除本站友链

常见问题

Q: 如何调整友链卡片排列？

友链卡片默认 2 列布局（响应式），如需修改请编辑 src/components/friends/FriendLinks.astro 的 CSS：

src/components/friends/FriendLinks.astro

.friend-links {
  grid-template-columns: repeat(2, minmax(16.5rem, 1fr)); /* 改为 3 试试 */
}

Q: 友链顺序如何排列？

友链按照 links 数组顺序显示，顺序调整直接在配置文件中移动对象位置即可。

Q: 可以给友链分组吗？

当前版本不支持分组。如需分组功能，可以：

1. 手动在 description 中说明分类
2. 或在 src/pages/friends/index.astro 中自定义渲染逻辑

Q: 头像/预览图加载慢怎么办？

建议：

1. 使用图床或 CDN 加速图片
2. 压缩图片体积（头像推荐 200x200，预览图宽度 1200px 以内）
3. 使用 WebP/AVIF 格式（体积更小）

Q: 如何禁用友链页面？

删除 src/pages/friends/index.astro 文件，并从导航栏配置中移除友链入口。

Q: 友链信息可以从外部文件加载吗？

可以。创建 src/data/friends.json：

src/data/friends.json

[
  {
    "url": "https://example.com/",
    "title": "示例站点",
    "desc": "站点简介",
    "author": "作者名",
    "avatar": "https://example.com/avatar.png"
  }
]

然后在 theme.config.ts 中导入：

src/theme.config.ts

import friendsList from "./data/friends.json";

export default defineConfig({
  // ...
  friends: {
    title: "友链",
    description: "我的伙伴们",
    links: friendsList,
  },
});

完整配置示例

src/theme.config.ts

export default defineConfig({
  // ...其他配置
  friends: {
    title: "友情链接",
    description: "一起进步的伙伴们",
    // 本站友链信息（可选）
    avatar: "https://mysite.com/avatar.png",
    color: "var(--color-blue)",
    siteImage: "https://mysite.com/preview.png",
    // 友链列表
    links: [
      {
        url: "https://astro.build/",
        title: "Astro",
        desc: "全站体验轻快的静态站点框架，适合内容型站点与博客。",
        author: "Astro Team",
        avatar: "https://avatars.githubusercontent.com/u/44914786?s=200&v=4",
        color: "var(--color-orange)",
        siteImage: "https://astro.build/assets/press/astro-logo-dark.svg",
      },
      {
        url: "https://svelte.dev/",
        title: "Svelte",
        desc: "编译时框架，现代与简洁，组件写起来很顺手。",
        author: "Svelte Team",
        avatar: "https://avatars.githubusercontent.com/u/23617963?s=200&v=4",
        color: "var(--color-red)",
      },
      {
        url: "https://vite.dev/",
        title: "Vite",
        desc: "快速的前端开发构建工具，HMR 体验很棒。",
        author: "Vite Team",
        avatar: "https://avatars.githubusercontent.com/u/65625612?s=200&v=4",
        color: "var(--color-blue)",
      },
      {
        url: "https://bun.sh/",
        title: "Bun",
        desc: "一体化 JavaScript 运行时，速度与工具链兼备。",
        author: "Bun Team",
        avatar: "https://avatars.githubusercontent.com/u/108928776?s=200&v=4",
        color: "var(--color-green)",
        siteImage: "https://bun.sh/logo.svg",
      },
    ],
  },
});