Notes 维护说明（中文主维护 + 英文自动同步）

Notes 维护说明（中文主维护 + 英文自动同步）

本仓库的 Notes 页面在 /_pages/notes.md，会分别展示两套笔记：

  • 英文：Jekyll collection notes-en，目录 _notes-en/
  • 中文：Jekyll collection notes-zh，目录 _notes-zh/

在 _config.yml 中，永久链接已配置为：

  • 英文：/notes/en/:title/
  • 中文：/notes/zh/:title/

推荐工作流

你只维护中文版本，英文版本交给 AI 自动生成：

  1. 新内容写在 _notes-zh/*.md
  2. push 到 main
  3. GitHub Actions 自动执行 scripts/translate_notes.py
  4. 生成或更新对应的 _notes-en/*.md

对应工作流文件：.github/workflows/translate-notes.yml

前置配置

在 GitHub 仓库配置中添加：

  • OPENAI_API_KEY（Secret，必填）
  • NOTES_TRANSLATE_MODEL（Actions Variable，可选，默认 gpt-4o-mini）

文件映射和同步规则

  • 文件名一一对应：_notes-zh/foo.md -> _notes-en/foo.md
  • front matter 保留，title 会翻译成英文
  • 脚本会写入 translation_hash，仅在中文源文件变化时重新翻译

发布策略（按时间和可见性控制）

Notes 页默认只展示“当前应公开”的内容，建议按下面方式控制：

  1. 时间发布：用 date 控制发布时间。未来时间不会出现在线上（future: false）。
  2. 全量隐藏：设置 published: false，整篇不发布。
  3. 仅从 Notes 列表隐藏：设置 note_hidden: true（页面仍可通过直链访问）。

系列化写作（推荐）

如果你想把笔记做成可连续阅读的系列，可以在 front matter 增加：

  • series: 系列唯一键（如 deepseek-zh）
  • series_title: 系列标题
  • series_desc: 系列简介（可选）
  • series_order: 在系列中的顺序（1,2,3…）

这样每篇底部会出现“上一篇 / 返回系列 / 下一篇”，并可在 /series/ 页面集中查看。

中英自动切换

文章页顶部支持 中文 | English 自动切换：

  1. notes（_notes-zh / _notes-en）
    默认按同名文件自动匹配（例如 foo.md 对应 foo.md）。

  2. posts 或跨集合（post <-> note）
    建议显式加这两个字段：

    • lang: zh 或 lang: en
    • translation_key: deepseek-data（同一对中英文使用同一个 key）

只要 key 一致，页面会自动找到另一语言版本并显示跳转链接。

推荐 front matter 模板：

---
title: "示例笔记标题"
date: 2026-03-12
layout: single
author_profile: true
published: true
note_hidden: false
series: "deepseek-zh"
series_title: "DeepSeek 中文笔记"
series_order: 1
lang: zh
translation_key: deepseek-data
---

新增中文笔记示例

文件：_notes-zh/2026-03-12-example.md

---
title: "多臂老虎机速记"
date: 2026-03-12
layout: single
author_profile: true
---

这里是正文。

本地预览

修改 _config.yml 后，请重启 jekyll serve，配置才会生效。