企业官网建设流程全解析

• 前端
• 文档

导读

本指南以仓库中 _teaching/2015-spring-teaching-2.md 这篇教学经历模板文档为入口，深入解析 academicpages.github.io（Academic Pages，一个基于 HTML 与 Markdown 的个人学术主页 GitHub Pages 模板）中"教学经历（Teaching）"页面从front matter 声明 → Jekyll Collection 收集 → 列表页循环渲染 → 详情页展示的完整链路。读完本文，你将掌握如何新增一条教学经历、每个字段的真实作用、列表与详情页分别由哪些模板渲染，以及如何用 Markdown 语法填充正文，直接可用于搭建自己的学术主页。

一、教学经历文档的定位：不只是占位符

_teaching/2015-spring-teaching-2.md是 Academic Pages 模板自带的教学经历示例文档。它的正文只有寥寥数行占位文本，但真正决定页面行为的是文件头部的 YAML front matter：

--- title: "Teaching experience 2" collection: teaching type: "Workshop" permalink: /teaching/2015-spring-teaching-1 venue: "University 1, Department" date: 2015-01-01 location: "City, Country" --- This is a description of a teaching experience. You can use markdown like any other post. Heading 1 ====== Heading 2 ====== Heading 3 ======

从源码结构看，这份文档承担两个职责：其一，作为_teaching/集合（collection）的一个真实条目，被 Jekyll 收集并渲染成独立页面；其二，作为模板样例，向使用者展示教学经历页可用的全部 front matter 字段。因此它虽然简短，却是理解整个教学板块渲染机制的钥匙。

二、front matter 字段逐个拆解：每个键的真实作用

结合 _config.yml 的集合定义与 _includes/archive-single.html 的渲染逻辑，可以逐字段确认其语义：

值得注意的细节是date的处理方式：_includes/archive-single.html 中使用了default: "1900-01-01"兜底，即使某条教学记录忘记写date，列表页也不会报错，而是显示 1900。这体现了模板对不完整 front matter 的容错设计。

三、从文件到页面：Jekyll Collection 的注册与渲染链路

3.1 集合注册：_config.yml中的 teaching 配置

任何放在_teaching/目录下的 Markdown 文件要成为"教学经历"，前提是它在站点配置中被声明为集合。_config.yml 中给出了明确配置：

collections: teaching: output: true permalink: /:collection/:path/ publications: output: true permalink: /:collection/:path/ portfolio: output: true permalink: /:collection/:path/ talks: output: true permalink: /:collection/:path/

其中output: true表示集合中的每个条目都会生成独立的静态 HTML 页面，permalink: /:collection/:path/则规定了 URL 结构——teaching集合下的2015-spring-teaching-2.md默认会得到/teaching/2015-spring-teaching-2/这样的路径（front matter 中的permalink可以覆盖该默认值）。

3.2 默认布局：teaching 条目的站点级默认值

紧接着的defaults配置为 teaching 集合统一注入了页面行为（_config.yml）：

# _teaching - scope: path: "" type: teaching values: layout: single author_profile: true share: true comments: true

这意味着你甚至不需要在每个教学经历文档里写layout，Jekyll 会自动为其套用single布局，并开启作者侧边栏（author_profile）、社交分享（share）和评论（comments）。

3.3 列表页：_pages/teaching.html的循环渲染

教学经历聚合页由 _pages/teaching.html 驱动，其核心逻辑只有几行：

{% include base_path %} {% for post in site.teaching reversed %} {% include archive-single.html %} {% endfor %}

• site.teaching是 Jekyll 根据_config.yml中的集合声明自动生成的集合对象；
• reversed让条目按 front matter 中的日期倒序展示（最新的课程排在前面）；
• 每个条目通过 _includes/archive-single.html 渲染，该模板内有一段专门针对 teaching 集合的分支逻辑：

{% if post.collection == 'teaching' %} <p> {{ post.type }}, <i>{{ post.venue }}</i>, {{ post.date | default: "1900-01-01" | date: "%Y" }} </p>

可以看到，列表条目最终展示为Workshop, *University 1, Department*, 2015这样的信息行——这正是你填写的type、venue、date三个字段的组合输出，格式由模板硬编码，无需手工排版。

3.4 详情页：single布局中的内容呈现

点击列表条目后进入详情页。teaching 条目默认使用single布局，_layouts/single.html 会：

1. 在页面头部渲染title为一级标题，并输出date（格式化为Month DD, YYYY）；
2. 将文档正文（front matter 之后的所有内容）渲染为page__content区块；
3. 渲染页脚元信息与分页导航（post_pagination）。

也就是说，正文中的

Heading 1 ====== Heading 2 ====== Heading 3 ======

这类 Setext 风格标题（用=与-表示 H1/H2）会被 Jekyll 的 Markdown 引擎正确解析为各级标题，与其他任何 Jekyll 帖子无异——这正是文档中那句 "You can use markdown like any other post" 的实际含义。

四、实操：如何新增一条自己的教学经历

基于上述机制，添加一条教学经历只需三步：

第 1 步：新建文档。在_teaching/目录下创建形如2016-spring-course-1.md的文件（文件名建议以时间开头，便于排序与识别）。

第 2 步：填写 front matter。参考模板补齐以下字段：

--- title: "机器学习导论" collection: teaching type: "Graduate course" permalink: /teaching/2016-spring-course-1 venue: "School of Computer Science" date: 2016-01-15 location: "Beijing, China" ---

第 3 步：撰写正文。在 front matter 之后自由使用 Markdown 描述课程大纲、教学目标、课件链接等。如需放置课件 PDF，可将其放入files/目录，然后按files/下的相对路径引用（如课件，注意 PDF 等二进制文件需先上传到仓库）。

保存后，Jekyll 会在下次构建时自动完成收集、排序与渲染：_pages/teaching.html的列表中出现新条目，同时生成独立详情页。

五、本地预览与验证

修改教学经历文档后，建议先本地预览再推送：

1. 安装依赖（Linux 下）：sudo apt install ruby-dev ruby-bundler nodejs；
2. 安装 Ruby 依赖：bundle install（如遇权限错误可执行bundle config set --local path 'vendor/bundle'后重试）；
3. 启动本地服务：bundle exec jekyll serve -l -H localhost，访问http://localhost:4000/teaching/查看教学列表页。

注意：Markdown 正文的修改会触发自动重建，但_config.yml中集合配置的变更需要重启 Jekyll 才生效（详见 README.md）。

六、扩展：teaching 集合与其他集合的对照

_config.yml中 teaching 与publications、portfolio、talks共享相同的集合注册模式，但各有定制：

• publications：列表页展示 "Published invenue, year"（见 archive-single.html），并提供论文 PDF、Slides、BibTeX 的下载链接逻辑；
• talks：使用专用的talk布局，_layouts/talk.html 中额外输出talk_type、venue、location信息；
• portfolio：常用于作品展示，支持grid网格视图。

可见 teaching 集合的 front matter 字段（type/venue/date/location）并非孤例，而是模板为"学术履历类内容"统一设计的信息模型，理解教学页面的机制后，可以举一反三地迁移到其他集合。

七、小结

_teaching/2015-spring-teaching-2.md表面上是占位文档，实则完整承载了 Academic Pages 教学板块的字段契约：collection声明归属、type/venue/date/location定义履历信息、permalink控制 URL，正文则复用标准 Markdown。这套机制由_config.yml的集合注册与默认值、_pages/teaching.html的循环、archive-single.html的分支渲染以及single布局的详情展示共同支撑，构成了一个"零代码新增页面"的声明式内容管线——你只需要填写 Markdown 文件，剩下的渲染交给 Jekyll 与模板完成。

• 前端
• 文档