Eleventy 博文实战:从 front matter 到文章集合与布局渲染——以 secondpost.md 为例
Eleventy 博文实战:从 front matter 到文章集合与布局渲染——以 secondpost.md 为例
导读
在 Eleventy 静态站点模板 中,每一篇博客文章(post)都是一份独立的内容文件,framework-boilerplates/eleventy/posts/secondpost.md 正是其中结构最典型的一篇示例博文。本文以它为主线,逐层拆解 Eleventy 博客中博文的完整生命周期:front matter 元数据如何声明、目录级数据文件 posts.json 如何把它们归入文章集合、post.njk 与 base.njk 双层布局如何完成渲染、文章间链接与标签如何工作,以及最终如何通过构建命令把 Markdown 变成可部署的 HTML 页面。读完本文,你将能够照着这套模板写出自己的第一篇(以及第二篇)Eleventy 博文,并清楚知道每个字段与文件的作用。
一、secondpost.md 在项目中的位置
在 framework-boilerplates/eleventy 目录下,内容文件统一放在 posts/ 子目录中,与它并列的还有 firstpost.md、thirdpost.md、fourthpost.md。模板的 README.md 明确说明:博文可以放在任意目录,只需要打上 post 标签即可被加入对应集合。也就是说,posts/ 只是约定俗成的目录,真正的"归类"由内容自身的元数据完成。
framework-boilerplates/eleventy/
├── _data/metadata.json # 全局站点元数据(标题、URL、RSS 配置等)
├── _includes/
│ ├── layouts/base.njk # 顶层 HTML 骨架
│ ├── layouts/post.njk # 博文布局(包裹 base.njk)
│ └── postslist.njk # 博文列表组件
├── posts/
│ ├── firstpost.md
│ ├── secondpost.md # 本文主角
│ ├── thirdpost.md
│ ├── fourthpost.md
│ └── posts.json # posts/ 目录级数据文件
├── feed/ # RSS / JSON Feed 模板
├── tags.njk / tags-list.njk # 标签页与标签列表
└── package.json # Eleventy 构建脚本与依赖
二、front matter:一篇博文的"身份证"
secondpost.md 的开头是一段 YAML front matter,这也是 Eleventy 识别一篇内容是否是独立页面的关键:
---
title: This is my second post.
description: This is a post on My Blog about leveraging agile frameworks.
date: 2018-07-04
tags:
- number 2
layout: layouts/post.njk
---
各字段的作用如下:
| 字段 | 取值示例 | 作用与说明 |
|---|---|---|
title |
This is my second post. |
文章标题,会被 post.njk 渲染为 <h1>,同时用于浏览器标题与导航 |
description |
This is a post on My Blog about ... |
文章摘要。在 base.njk 中作为 <meta name="description"> 输出;若未设置则回退到 metadata.description |
date |
2018-07-04 |
文章发布日期,用于按时间排序与时间标签渲染,可省略(省略时以文件创建时间为准) |
tags |
number 2 |
标签数组,单个标签也按数组写法。该字段同时决定文章归属哪个集合 |
layout |
layouts/post.njk |
指定渲染该文件使用的布局模板,路径相对于 _includes/ 目录 |
值得注意的一个细节:posts.json 目录数据文件为 posts/ 下所有内容统一注入了 tags: ["posts"]:
{
"tags": [
"posts"
]
}
结合 posts.json 与 secondpost.md 自身的 tags: [number 2],这篇文章实际会被同时归入 posts 与 number 2 两个集合标签。这就是 Eleventy 中"目录级数据 + 文件级数据合并"的数据层机制:目录级 front matter 提供公共元数据,文件级 front matter 负责差异化配置。
三、从 Markdown 到 HTML:post.njk 与 base.njk 的双层渲染
secondpost.md 声明了 layout: layouts/post.njk,整篇 Markdown 正文会被转换成 HTML 后注入到布局的 {{ content | safe }} 位置。post.njk 是博文专属布局:
---
layout: layouts/base.njk
templateClass: tmpl-post
---
<h1>{{ title }}</h1>
<time datetime="{{ page.date | htmlDateString }}">{{ page.date | readableDate }}</time>
{%- for tag in tags | filterTagList -%}
{%- set tagUrl %}/tags/{{ tag | slug }}/{% endset -%}
<a href="{{ tagUrl | url }}" class="post-tag">{{ tag }}</a>
{%- endfor %}
{{ content | safe }}
它做了四件事:
- 标题输出:
{{ title }}直接取自 front matter 的title字段; - 日期格式化:
date字段经过htmlDateString与readableDate两个过滤器分别生成<time>的datetime属性与可读文本(这两个过滤器由 package.json 中的luxon依赖提供); - 标签链接:遍历
tags(经filterTagList过滤掉posts等非展示标签),并用slug过滤器生成/tags/xxx/形式的标签页 URL; - 正文注入:
{{ content | safe }}输出渲染后的 Markdown 正文。
而 post.njk 自身又声明 layout: layouts/base.njk,因此最终页面由 base.njk 提供完整的 HTML5 骨架:<head> 中的页面标题、meta description、两套 CSS(站点样式 index.css 与代码高亮 prism-base16-monokai.dark.css)、Atom/JSON Feed 的 <link rel="alternate"> 声明,以及基于 eleventy-navigation 插件渲染的顶部导航栏。布局层层嵌套(base ← post ← 内容文件),是 Eleventy 中典型的级联布局模式。
四、文章间导航:url 过滤器与"上一篇/下一篇"
secondpost.md 的正文中有一段非常值得照抄的链接写法:
<a href="{{ '/posts/firstpost/' | url }}">First post</a>
<a href="{{ '/posts/thirdpost/' | url }}">Third post</a>
这里没有硬编码相对路径,而是把路径交给 url 过滤器处理,由 Eleventy 统一补全站点前缀(pathPrefix),保证在子路径部署(如 Vercel Preview 环境)时链接依然正确。这是本模板中跨文章引用的标准姿势。
除了手动写链接,post.njk 还基于 collections.posts 自动生成了"上一篇/下一篇"导航:
{%- set nextPost = collections.posts | getNextCollectionItem(page) %}
{%- set previousPost = collections.posts | getPreviousCollectionItem(page) %}
{%- if nextPost or previousPost %}
<hr>
<ul>
{%- if nextPost %}<li>Next: <a href="{{ nextPost.url | url }}">{{ nextPost.data.title }}</a></li>{% endif %}
{%- if previousPost %}<li>Previous: <a href="{{ previousPost.url | url }}">{{ previousPost.data.title }}</a></li>{% endif %}
</ul>
{%- endif %}
getNextCollectionItem / getPreviousCollectionItem 按日期对 posts 集合排序,自动找出当前页的相邻文章。这意味着你只需新增博文文件并写好 front matter,页面间的上下篇导航就会自动生成,无需手工维护。
五、标签体系:从博文标签到标签聚合页
secondpost.md 的标签是 number 2,firstpost.md 使用 another tag,thirdpost.md 使用 second tag 与 posts with two tags。这些标签除了在单篇文章页展示,还驱动了站点的标签聚合功能:
tags.njk与tags-list.njk位于framework-boilerplates/eleventy根目录,它们遍历所有页面标签,生成/tags/标签名/的归档页与标签索引页;- 每个标签页会列出该标签下的全部文章,URL 由
slug过滤器从标签名生成(如number 2→/tags/number-2/); - 如果某个标签从未在任何内容中出现,对应的归档页就不会生成——标签数据完全由内容反向驱动。
因此,为文章打标签(在 front matter 中追加 tags 数组项)是 Eleventy 博客中成本最低的内容组织方式,文章一多,标签归档便自动成型。
六、正文结构:占位内容与真实写作
secondpost.md 的正文是模板自带的占位文案(placeholder copy),其内部结构是 Eleventy 博客中标准的 Markdown 组织方式,可直接替换为真实内容:
- 正文段落:连续的自然段,会被
markdown-it(见 package.json 的devDependencies)解析为标准 HTML 段落; - 二级标题
## Section Header:用于在长文中切分小节;配合markdown-it-anchor插件,标题会自动生成锚点; - 内联 HTML:
secondpost.md直接使用了<a href="{{ ... | url }}">这种 Nunjucks 表达式写在 HTML 标签内的写法,说明 Eleventy 内容文件里的模板语法与 Markdown 是可以混用的——需要动态 URL、循环或条件时,可以直接借助模板引擎能力。
同时,firstpost.md 与 thirdpost.md 还展示了带语法高亮的代码块写法(js/2/4 这种带行号高亮标记的围栏代码块),secondpost.md 中虽然未包含代码块,但同目录文章证明了该能力开箱即用。写作时只需在 front matter 中如实填写标题、描述与日期,正文使用普通 Markdown 即可。
七、如何运行与验证
模板的 package.json 预置了完整脚本:
"scripts": {
"build": "eleventy",
"watch": "eleventy --watch",
"serve": "eleventy --serve",
"start": "eleventy --serve",
"debug": "DEBUG=* eleventy"
}
- 安装依赖:
npm install - 编辑 metadata.json,把
title、url、author等替换成你自己的站点信息(这些全局数据会被base.njk、feed模板引用); - 本地开发:
npm run serve(即eleventy --serve),Eleventy 会启动本地服务并监听文件变化实时重建,浏览器打开即可预览secondpost.md渲染后的文章页; - 生产构建:
npm run build,产物输出到_site/目录; - 调试:
DEBUG=* eleventy可输出详细的构建日志,排查集合、数据与布局问题时非常有用。
构建完成后,secondpost.md 会被输出为 _site/posts/secondpost/ 下的静态 HTML,同时站点首页(index.njk 通过 _includes/postslist.njk 列出全部文章)、标签页、RSS/JSON Feed(feed/ 目录,读取 metadata.json 中的 feed 配置)也会一并生成。整个站点是纯静态产物,可直接托管到任意静态平台。
八、把占位内容换成真实文章的最佳实践
结合上面的分析,将 secondpost.md 改造成自己的真实博文,只需遵循以下清单:
- 重写 front matter:给出有意义的
title与description(后者会进入页面的 meta description,影响 SEO 与分享摘要); - 更新
date:改为真实发布日期,它决定文章在集合中的排序位置与展示时间; - 调整
tags:去掉示例标签number 2,换成你实际的主题标签;需要加入"全部文章"集合时保持posts.json注入的posts标签不动即可; - 重写正文:替换占位段落,长文用
##分节,需要代码示例时使用带语言标记的围栏代码块; - 保留布局声明:
layout: layouts/post.njk不要改动,它是文章页渲染与上下篇导航生效的前提; - 用
url过滤器写内部链接:跨文章引用时始终写成{{ '/posts/xxx/' | url }}的形式,避免硬编码路径在子路径部署下失效。
完成上述步骤后重新 npm run serve,就能在本地看到一篇结构完整、具备标签归档与上下篇导航的正式博文。
参考文件速查
- 博文样例:framework-boilerplates/eleventy/posts/secondpost.md、firstpost.md、thirdpost.md
- 目录级数据文件:framework-boilerplates/eleventy/posts/posts.json
- 布局模板:framework-boilerplates/eleventy/_includes/layouts/post.njk、base.njk
- 站点全局数据:framework-boilerplates/eleventy/_data/metadata.json
- 构建脚本与依赖:framework-boilerplates/eleventy/package.json
- 项目说明与运行指引:framework-boilerplates/eleventy/README.md