EAL Weekly

EAL Weekly 是一个面向大众的 AI 周报与知识栏目，采用中英双语内容结构，文章以 Markdown 文件为源，自动生成页面、列表和周次排序。

1. 文章目录

所有文章统一放在 src/episodes/ 目录下。这个文件夹可以直接用 Obsidian 打开和管理，但需要注意：

• Obsidian 只能帮你编辑和查看 Markdown，它不会让网页自动出现"相关文章"等功能

• 网页上的标签必须写在每篇文章的 frontmatter tags: 里（见第 2 节）

• 文件名可以按下面的方式命名：

• eal-weekly-what-is-it-zh.md

• eal-weekly-what-is-it-en.md

其中：

• zh 表示中文版本
• en 表示英文版本
• 同一篇文章的中文和英文文件应使用相同的基础名称，例如 eal-weekly-what-is-it。

Obsidian 用户注意：你可以在 Obsidian 中创建、编辑这些文件。只要保证 frontmatter 里的 tags: 写对了，网页上的"相关文章"就会正常工作。Obsidian 里的 #标签 或图谱链接不会同步到网站。

如果一篇文章有对应的另一语言版本，网页会自动识别并在文章页顶部显示语言切换按钮：

• 中文版本
• English Version

2. 文章必须写的日期格式

每篇 Markdown 文件的 frontmatter 必须包含日期，使用固定格式：

---
layout: layouts/episode.njk
title: "EAL Weekly 是什么？"
date: 2026-08-24
language: zh
tags:
  - journal
  - introduction
summary: "我们为什么做这个期刊，以及它想解决什么问题。"
---

日期必须使用：

• YYYY-MM-DD
• 例如：2026-08-24

网页会根据这个日期自动计算周次，并按时间倒序排列。也就是说：

• 文章的写作日期 = 排序依据
• date 字段 = 周次归属与展示时间
• 如果没有日期，文章不会参与正确排序

3. 文章添加步骤

1. 在 src/episodes/ 目录下新建一个 Markdown 文件。
2. 复制 src/episodes/_template.md 模版内容。
3. 修改 title、date、language、summary 和正文。
4. 如果该文章有中英双语版本，使用相同的基础命名，并分别写入 zh / en。
5. 运行：

npm run build

6. 生成静态站点后，文章会自动出现在首页精选列表与文章列表中。

4. 自动打标签（可选）

项目提供了一个基于关键词的自动打标签脚本，运行后会根据文章内容自动给 frontmatter 添加 tag：

# 扫描整个 src/episodes/ 目录
npm run tag

# 只处理单篇文章
npm run tag -- src/episodes/your-article-zh.md

它会保留你已经写好的 tag，并根据正文内容自动补充。例如文章提到 OpenAI、GPT、ChatGPT 会自动加上 openai；提到 agent、智能体会加上 agent。

如果你想用更智能的 AI 自动打标签（比如调用 OpenAI API 分析主题），可以在此基础上扩展脚本，接入任意大模型 API。

5. 相关文章推荐

每篇文章页面底部会自动显示"相关文章"。相关度基于：

1. 共同标签数量（最重要）
2. 是否同一语言
3. 是否同一周次
4. 发布日期是否接近

系统会自动排除当前文章本身，以及它的中英翻译版本，避免重复推荐。

这个功能完全由 Eleventy 在构建时计算生成，不需要 Obsidian，也不需要你手动维护链接。

6. MD 模版

模版文件：src/episodes/_template.md

内容示例：

---
layout: layouts/episode.njk
title: "Article Title"
date: 2026-08-24
language: zh
tags:
  - journal
  - introduction
summary: "Short summary in one or two sentences."
---

## Overview

Write the article body here.

## Why this matters

Explain the topic in plain language.

## Key takeaways

- Point one
- Point two
- Point three

7. 周次识别规则

网页会读取每篇文章的 date 字段，并自动计算该文章所属周次，例如：

• 2026-08-24 → Week 35
• 2026-08-30 → Week 35

排序规则：

• 默认按日期从新到旧排列
• 首页精选列表展示最新的前几篇
• 文章页会显示当前文章所属周次与日期标签

8. 开发命令

npm install
npm run dev
npm run build
npm run tag        # 自动给文章打标签

9. 本地预览与自动刷新

本地预览

在项目根目录执行：

npm run dev

然后打开浏览器访问：

http://localhost:8080

Eleventy 会自动监控以下文件的变化：

• Markdown 文章
• Nunjucks 模板
• CSS 和 JS
• 其他静态资源

一旦文件更新，页面会自动重新生成并刷新。

生产构建

npm run build

生成目录为：

_site/

10. GitHub Pages 部署步骤

这个项目支持 GitHub Pages 自动部署。已在仓库中添加工作流文件：

• .github/workflows/pages.yml

部署流程：

1. 代码推送到 main 分支
2. GitHub Actions 自动触发 workflow
3. 安装依赖并执行 npm run build
4. 将 _site 目录部署到 GitHub Pages
5. 页面自动更新

GitHub 仓库设置

在 GitHub 仓库中：

1. 进入 Settings
2. 选择 Pages
3. Source 选择 GitHub Actions

然后每次合并到 main 后，GitHub Pages 都会自动重新构建并发布。

11. User Site 与 Project Site 的区别

User Site（用户站点）

这是 GitHub 提供的个人主页形式，网址通常是：

https://<username>.github.io/

特点：

• 这是一个个人站点入口
• 适合放个人主页、博客、作品集
• 通常专门用于一个用户或个人品牌

Project Site（项目站点）

这是仓库对应的项目页面，网址通常是：

https://<username>.github.io/<repository-name>/

特点：

• 适合放项目文档、案例、周报、博客站点
• 路径中带仓库名
• 例如本仓库当前配置会使用：

https://<username>.github.io/EALWeekly/

自定义域名

本项目的生产域名是：

https://ealweekly.me/

自定义域名站点部署在根路径，而不是 /EALWeekly/。因此，GitHub Actions 构建时不应设置 BASE_URL（Eleventy 默认使用 /）；否则首页和文章链接会被错误地生成成 https://ealweekly.me/EALWeekly/... 并导致 404。

src/CNAME 会被 Eleventy 原样复制到发布产物的根目录，GitHub Pages 据此持续绑定 ealweekly.me。在 GitHub 仓库 Settings → Pages 中也应显示相同的 Custom domain，并启用 Enforce HTTPS（证书签发完成后可用）。

原 GitHub Pages 项目地址

不使用自定义域名时，这个仓库的 GitHub Pages 项目地址是：

https://jasonsun2009cn.github.io/EALWeekly/

如需临时为该项目地址构建，可运行 BASE_URL=/EALWeekly/ npm run build。生产部署则始终使用根路径 /。

12. 说明

• 文章以 Markdown 为主源，不再依赖测试数据。
• 当前站点支持中英双语文章切换。
• 首页已保留“精选文章列表”区域，用于突出重要文章。
• 通过 GitHub Pages + GitHub Actions，可以实现：更新 MD 文档 → push → 自动部署 → 站点刷新。