al-folio 操作汇总

更新al-folio版本

版本差距较小

使用rebase进行修改，适合改动少、上游差距不大时使用

1. rebase分析版本

   git fetch upstream
   git checkout main
   git rebase 0.16.3
   

2. 修改冲突内容后，进行提交

   git add .
   git commit -a -m 'xxx'
   

版本差距较大

当冲突过多、版本相差较大时，直接重建分支并迁移内容性价比较高，因为冲突过多的时候直接推倒重建反而代价更小

步骤

1. 新建干净分支（基于上游最新版）

   git checkout -b fresh-upstream upstream/main
   

2. 从旧仓库迁移文件
   • _data/socials.yml 社交媒体配置
   • _data/repositories.yml github的库信息
   • _drafts 草稿文件
   • _pages/about.md 个人简介
   • _pages/cv.md 个人简历模板，当使用resume.json作为cv的参考时，需要将cv_format的配置从rendercv改到jsonresume
   • _posts/ 个人博客文件
   • assets/img/ 头像（prof_pic.png）、二维码（wechat-qr.png）、文章图（post_img）、收藏夹图标（favicon.png）
   • assets/json/resume.json 个人简历配置
   • _config.yml 博客整体配置文件，这里只合并个人字段，不要整文件覆盖

3. 除非涉及到深度定制，或者有其他定制需求，否则其余文件不要迁移

4. 本地启动检查页面和链接 docker compose up -d

异常排查记录

排查 socials 中 wechat-qr 报错

现象

启动时在渲染 about 页面报错：

Liquid Exception: undefined method `split` for nil

原因

_data/socials.yml 中的 wechat_qr 不是 jekyll-socials 识别的标准字段，会被当作自定义社交项，但值只是字符串（非 logo/title/url 结构），导致插件尝试解析 logo 时崩溃。

解决方案

1. 直接注释 wechat_qr项，使其在search.liquid.js中走相关逻辑，防止``逻辑中出现异常
2. 使用custom_social的方式来自定义WeChat社交项

custom_social 的 logo 必须是网络地址

custom_social 中的 logo 使用本地路径时会触发插件内部 relative_url 报错。建议使用完整的 https URL。

配置 CV 的正确方式

在 al-folio 0.16.3版本中，简历内容主要在 _data/cv.yml 中维护，_pages/cv.md 只是渲染入口。 如果升级后 CV 显示异常，优先检查：

• _data/cv.yml 是否符合新版结构
• _pages/cv.md 是否引用了正确的 layout / 数据源