用 al-folio 搭建数据科学课程主页：《Data Science Fundamentals》课程页结构全解析

用 al-folio 搭建数据科学课程主页：《Data Science Fundamentals》课程页结构全解析

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio

本篇技术指南以 al-folio 仓库中的课程页示例 _teachings/data-science-fundamentals.md 为主体，系统讲解如何使用_teachings集合为课程创建结构化主页：从 frontmatter 元数据、逐周教学日程（schedule）到正文信息块的完整写法，并深入渲染链路、Google 日历嵌入与本地构建验证。读完本文，你将掌握一门新课程从新增 Markdown 文件、配置字段到在/teaching/页面自动分组展示的完整实战方案，可直接复用于任意学术课程站点。

课程页文档的定位：一篇完整的 Jekyll 集合条目

在 al-folio 中，_teachings/data-science-fundamentals.md 是一份“Data Science Fundamentals”课程的完整内容文件（2024 年春季学期，授课教师 Prof. Data，上课时间周一与周三 14:00-15:30，地点 Science Building Room 202）。它由两部分组成：

• frontmatter 元数据：layout: course、title、description、instructor、year、term、location、time、course_id，以及一个包含 6 周详细安排的schedule列表；
• Markdown 正文：## Course Overview、## Prerequisites、## Textbooks、## Grading四个小节，用于承载课程概览、先修要求、推荐教材与评分标准等自由文本内容。

从仓库定位看，这类文件属于 v1.x 架构中的starter 示例内容。docs/ARCHITECTURE.md 明确说明 al-folio v1.x 是“thin Jekyll starter, not a theme”，仓库只拥有接线配置、示例内容（_pages、_posts、_projects、_news、_teachings、_books、_bibliography）、文档与跨插件测试；而真正的运行时（course布局、courses.liquid渲染等）则归属al_folio_core等版本化 gem。因此，本文件的价值在于：它是一份可直接照抄、字段齐全、结构规范的课程页模板。

前置接线：teachings 集合在 Jekyll 配置中的注册

课程页能正常渲染，依赖 _config.yml 中的集合声明：

collections: books: output: true news: defaults: layout: post output: true projects: output: true teachings: output: true

要点说明：

• teachings:集合声明了output: true，意味着_teachings/下每个 Markdown 文件都会被 Jekyll 构建为独立页面（这与books、news、projects一致）；
• 与news不同，teachings没有在集合级指定默认layout，因此每个课程文件必须自己声明layout: course，否则无法套用课程布局；
• _teachings/目录下目前有两份示例：data-science-fundamentals.md（6 周、Spring 2024）与 introduction-to-machine-learning.md（8 周、Fall 2023，含第 6 周 Midterm Exam），后者可作为多周、含考试周安排的第二种参考写法。

frontmatter 字段逐项解析

课程页的元数据全部集中在 YAML frontmatter 中。docs/CUSTOMIZE.md 的 “Creating a teachings collection” 一节给出了权威字段说明，结合本示例文件可归纳为以下表格：

两点关键约束来自 docs/CUSTOMIZE.md：

1. 每个课程文件的course_id必须唯一；
2. 课程在/teaching/页面按year分组展示，同年内按term排序，schedule小节会被自动格式化为表格。

schedule：逐周教学日程的数据结构

schedule是本示例文件中最具复用价值的结构化数据。它以列表形式组织，每周包含week、date、topic、description与materials（课程材料列表，每项含name与url）。原始 6 周安排完整罗列如下：

对应的 YAML 结构（以第 1 周为例）为：

schedule: - week: 1 date: Feb 5 topic: Introduction to Data Science description: Overview of the data science workflow and key concepts. materials: - name: Syllabus url: /assets/pdf/example_pdf.pdf - name: Slides url: /assets/pdf/example_pdf.pdf

实操说明：

• 课程材料url指向仓库内的相对路径资源，例如本仓库实际存在的 assets/pdf/example_pdf.pdf，示例中讲义、作业均复用了该占位 PDF；如果材料托管在外部平台，可替换为相应资源地址（请以你自己的合法资源为准，避免沿用示例占位）；
• description建议用一句话精确概括当周讲授内容，便于学生在课表页快速定位；
• 若某周没有材料（例如考试周），可以像 introduction-to-machine-learning.md 第 6 周那样省略materials字段，仅保留week、date、topic、description。

正文部分：概览、先修、教材与评分

frontmatter 之下的 Markdown 正文会在课程独立页面中展示，适合放不适合结构化表格的内容。本示例给出了四个标准小节：

• Course Overview：明确课程目标与学习成果。本课程提供数据科学原理与实践的综合导论，学生将：学习端到端的数据科学工作流、获得数据操作工具的实操经验、培养数据可视化与表达技能、运用统计方法从数据中提炼洞察；
• Prerequisites：先修要求。基础编程能力（最好是 Python）、入门统计知识、熟悉基础代数；
• Textbooks：推荐教材。Wes McKinney 的《Python for Data Analysis》、Joel Grus 的《Data Science from Scratch》；
• Grading：评分构成。作业 50%、项目 40%、课堂参与 10%。

这套“学习成果 + 先修 + 教材 + 评分”的结构是学术课程页的通用模板，可直接沿用到任意课程。你也可以在正文中追加其他 Markdown 小节（如课程政策、考核日程、Office Hours），正文会原样呈现在课程详情页。

渲染链路：从 Markdown 到 /teaching/ 页面

课程集合的展示由 _pages/teaching.md 驱动，其内容核心是两行 include：

{% include calendar.liquid calendar_id='test@gmail.com' timezone='Asia/Shanghai' %} {% include courses.liquid %}

• courses.liquid：负责遍历_teachings集合，按year分组、term排序渲染所有课程入口，并指向各课程的独立页面；
• calendar.liquid：嵌入 Google 日历（详见下一节）；
• 页面 frontmatter 中声明了calendar: true，这是日历脚本加载的开关——docs/CUSTOMIZE.md 指出，只有开启该字段的页面才会加载日历相关脚本，避免无关页面白白引入脚本。

从 v1.x 架构看，course布局与courses.liquid、calendar.liquid这类 include 属于 gem 运行时（al_folio_core），而非 starter 仓库内容。这一点对应 docs/ARCHITECTURE.md 描述的“静默失败”模式：若 gem 未加载或开关未开启，标签会输出空字符串而不报错。因此排查“课程页不显示”时，应依次检查：gem 是否同时存在于 Gemfile 与_config.yml的plugins:列表、集合是否声明output: true、页面 frontmatter 是否开启对应开关。

在课程页中嵌入 Google 日历

教学页支持直接内嵌 Google 日历，便于集中展示课程安排。基础用法（来自 docs/CUSTOMIZE.md）：

{% include calendar.liquid calendar_id='your-calendar-id@group.calendar.google.com' timezone='Your/Timezone' %}

参数说明：

• calendar_id：Google 日历 ID，可在 Google Calendar 设置 → 集成日历 → Calendar ID 中获取（示例文件里用的是占位值test@gmail.com，实际部署时务必替换）；
• timezone：时区，例如UTC、Asia/Shanghai、America/New_York，默认UTC（当前示例页使用了Asia/Shanghai）；
• style：可选参数，用于自定义 iframe 样式，例如style='border:0; width:100%; height:800px;'，默认值为border:0; width:100%; height:600px;。

使用前提：承载日历的页面 frontmatter 必须声明calendar: true，否则脚本不会加载。

实战：新增一门课程并本地验证

参照本示例新增一门课程，只需三步：

1. 创建课程文件：在_teachings/下新建your-course.md，复制本示例的 frontmatter 骨架，填写layout: course、唯一的course_id、title、year，并按需补充instructor、term、location、time、description与逐周schedule；
2. 补充正文：在 frontmatter 后追加 Course Overview、Prerequisites、Textbooks、Grading 等 Markdown 小节；
3. 本地构建验证：从仓库根目录按 AGENTS.md 的已验证命令集执行：

bundle install bundle exec jekyll build --baseurl /al-folio

注意两点（对应 AGENTS.md 的说明）：本仓库_config.yml已设置baseurl: /al-folio，直接执行bundle exec jekyll build即可，--baseurl /al-folio属于冗余但无害的写法；本地开发服务器地址为http://localhost:4000/al-folio/。若使用 Docker 方式运行，AGENTS.md 给出的验证路径是docker compose up -d后访问http://127.0.0.1:8080/al-folio/。

构建完成后，可在/teaching/页面看到新课程自动出现在对应year分组中，并与其term排序位置一致；点击课程入口即进入由schedule自动生成表格的课程详情页。

常见问题与排查清单

• 课程页不出现/不渲染：优先检查集合声明。teachings集合必须在 _config.yml 中声明且output: true；文件 frontmatter 必须写layout: course，且course_id不与已有课程重复；
• 分组与排序不符合预期：year用于分组、term用于同年排序，确认这两个字段拼写与取值规范（如Fall、Spring、Summer）；
• 日历不显示：检查页面 frontmatter 是否开启calendar: true，并确认calendar_id已替换为真实日历 ID、时区参数合法；
• 功能静默失效：v1.x 采用“Gemfile 与_config.yml两处一致”的激活契约，任何依赖 gem 的功能若只改了一处配置都会无报错地不生效，排查时务必两处同时核对。

参考文件索引

• 课程页示例：_teachings/data-science-fundamentals.md、_teachings/introduction-to-machine-learning.md
• 集合配置：_config.ymlcollections 段
• 展示页面：_pages/teaching.md
• 官方指南：docs/CUSTOMIZE.md（课程集合）、docs/CUSTOMIZE.md（Google 日历嵌入）
• 架构与边界：docs/ARCHITECTURE.md、AGENTS.md
• 材料占位资源：assets/pdf/example_pdf.pdf

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio