Atomeocean Logbook

简体中文

English

简体中文

English

主题

The avatar of contributor named as JackJack
The avatar of contributor named as Bojack WangBojack Wang
The avatar of contributor named as CopilotCopilot
The avatar of contributor named as Claude Opus 5 (1M context)
Claude Opus 5 (1M context)

文章中作者信息 ​

发表于 2025-07-17
最后修改 2026-08-29
阅读量 —

文章顶部的作者栏由 ContributorWrapper 组件渲染，作者信息有两个来源：

  1. git 提交历史 — 插件自动从文章的 git 历史中读取提交者
  2. frontmatter 的 authors 字段 — 手动指定作者，显示在 git 作者之前

两个来源都会先通过 docs/_data/contributors.ts 中的贡献者档案做映射（插件配置 mapAuthors: allContributors），匹配到档案后统一显示档案里的名字和头像。团队信息页（/team-information/team.html）也使用同一份数据。

添加贡献者档案 ​

在 docs/_data/contributors.ts 的 currentContributors（在职）或 legacyContributors（离职）数组中添加：

ts
{
  avatar: AVATAR_LINKS.xxx,        // 头像，空串或不传时使用默认头像
  name: '显示在网页上的名字',
  username: 'github用户名',
  mapByNameAliases: ['git本地配置的名字', '其他名字'],  // git 提交者名字的映射
  title: 'Developer',              // 不传时默认 Contributor / Alumni
  links: [
    { type: '', icon: 'github', link: SOCIAL_LINKS.github('github用户名') },
    { type: '', icon: 'linkedin', link: SOCIAL_LINKS.linkedin('linkedin用户名') },
  ],
},

git 提交者的名字（git config user.name）如果和 name、username 都不一致，务必写进 mapByNameAliases，否则文章作者栏无法匹配到档案。

头像统一放在仓库的 docs/public/assets/webp/author-avatar/，转成 webp、命名为 <slug>.webp，在 AVATAR_LINKS 里按 /assets/webp/author-avatar/<slug>.webp 引用。这个文件同时给作者主页的 selfie-src 用，不需要准备两张。建议正方形、边长不小于 448px。

暂时拿不到本人头像就把值留成空串，数组末尾的 contributor.avatar || defaultAvatar 会兜底成默认头像。旧图床 jpqae.atomeocean.com 已下线，不要再往 AVATAR_LINKS 里填该域名的链接；getAvatarLink() 指向的 atomeocean.cn/contributor-avatar/ 是历史头像的存放位置，仍在用的条目保持不动即可。

在文章中指定作者 ​

在文章的 frontmatter 中添加 authors 字段：

markdown
---
authors:
  - Colton
  - Leo
---

<!-- body -->

名字需要能匹配到贡献者档案的 name、username 或 mapByNameAliases 之一，按 frontmatter 中的顺序显示在作者栏最前面。

为作者创建作者主页 ​

配置作者主页后，文章作者栏的按钮和团队信息页的成员卡片都可以跳转到作者的个人页面。分两步：

1. 创建主页文件 ​

在 docs/zhHans/guide/author-list/ 下创建 <slug>.md，使用 AuthorPage 组件（局部导入，不做全局注册）：

markdown
---
title: 作者名
layout: page
sidebar: false
---
<script setup>
import AuthorPage from '@ao-components/AuthorPage.vue';
</script>

<AuthorPage
  author-name="作者名"
  role="Atomeocean 专栏作者"
  location="Jersey City, NJ"
  based-in="本人长期在美国境内工作与生活。"
  tagline="一句话介绍"
  selfie-src="/assets/webp/author-avatar/<slug>.webp"
/>

AuthorPage 还支持 location（所在城市 / 州，显示在顶部身份胶囊旁）、basedIn（常驻情况的完整表述，显示在正文区数据卡下方）、topics（领域标签）、highlights（亮点数据）、works（代表作卡片）、打赏二维码等属性，对应区块在属性为空时自动隐藏。数据要有出处：署名文章数可以用 authors: frontmatter 统计，开发者可以用 git 提交数。参考现有页面：colton-t-0821.md、leo-l-0710.md、jack.md、bojian.md。

selfie-src 用的就是贡献者档案里的那张头像，同一个 /assets/webp/author-avatar/<slug>.webp，页面上按 224×224 裁切显示。

2. 在贡献者档案中登记 slug ​

在 contributors.ts 对应条目上加一行 authorPageSlug，值为主页文件名（不含 .md）：

ts
{
  name: 'Jack',
  username: 'k90zz',
  authorPageSlug: 'jack',   // 对应 guide/author-list/jack.md
  // ...
},

加上之后自动生效，无需改动任何组件：

  • 文章作者栏的按钮链接到 /guide/author-list/<slug>，站内路由跳转，优先级高于 GitHub 等社交链接
  • 团队信息页（中英文）的成员卡片自动出现作者主页图标（新标签页打开）

更新已有贡献者 ​

改名或换头像时，有几处必须同步，否则历史文章的作者栏会掉档：

  • 改 name 时把旧名字加进 mapByNameAliases。 已发布文章 frontmatter 里写的还是旧名字，git 历史里的提交者名也无法更改；旧名字一旦从档案里消失，这些文章的作者栏就匹配不到档案，退化成没有头像和链接的纯文本。
  • 不要跟着改 authorPageSlug 和主页文件名。 主页 URL 是 /guide/author-list/<slug>，已经被文章作者栏、团队信息页和站外分享引用。改名只改页面里的 author-name 和 frontmatter title，slug 保持原样。
  • 换头像时两处一起改。 contributors.ts 的 avatar 和主页的 selfie-src 指向同一个文件。