Eleventy 博文实战:从 front matter 到文章集合与布局渲染——以 secondpost.md 为例

原创2026-09-17 12:54:021,843 阅读
文章标签:示例工程前端后端

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 }}

它做了四件事:

  1. 标题输出:{{ title }} 直接取自 front matter 的 title 字段;
  2. 日期格式化:date 字段经过 htmlDateString 与 readableDate 两个过滤器分别生成 <time> 的 datetime 属性与可读文本(这两个过滤器由 package.json 中的 luxon 依赖提供);
  3. 标签链接:遍历 tags(经 filterTagList 过滤掉 posts 等非展示标签),并用 slug 过滤器生成 /tags/xxx/ 形式的标签页 URL;
  4. 正文注入:{{ 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"
}
  1. 安装依赖:npm install
  2. 编辑 metadata.json,把 title、url、author 等替换成你自己的站点信息(这些全局数据会被 base.njk、feed 模板引用);
  3. 本地开发:npm run serve(即 eleventy --serve),Eleventy 会启动本地服务并监听文件变化实时重建,浏览器打开即可预览 secondpost.md 渲染后的文章页;
  4. 生产构建:npm run build,产物输出到 _site/ 目录;
  5. 调试:DEBUG=* eleventy 可输出详细的构建日志,排查集合、数据与布局问题时非常有用。

构建完成后,secondpost.md 会被输出为 _site/posts/secondpost/ 下的静态 HTML,同时站点首页(index.njk 通过 _includes/postslist.njk 列出全部文章)、标签页、RSS/JSON Feed(feed/ 目录,读取 metadata.json 中的 feed 配置)也会一并生成。整个站点是纯静态产物,可直接托管到任意静态平台。

八、把占位内容换成真实文章的最佳实践

结合上面的分析,将 secondpost.md 改造成自己的真实博文,只需遵循以下清单:

  1. 重写 front matter:给出有意义的 title 与 description(后者会进入页面的 meta description,影响 SEO 与分享摘要);
  2. 更新 date:改为真实发布日期,它决定文章在集合中的排序位置与展示时间;
  3. 调整 tags:去掉示例标签 number 2,换成你实际的主题标签;需要加入"全部文章"集合时保持 posts.json 注入的 posts 标签不动即可;
  4. 重写正文:替换占位段落,长文用 ## 分节,需要代码示例时使用带语言标记的围栏代码块;
  5. 保留布局声明:layout: layouts/post.njk 不要改动,它是文章页渲染与上下篇导航生效的前提;
  6. 用 url 过滤器写内部链接:跨文章引用时始终写成 {{ '/posts/xxx/' | url }} 的形式,避免硬编码路径在子路径部署下失效。

完成上述步骤后重新 npm run serve,就能在本地看到一篇结构完整、具备标签归档与上下篇导航的正式博文。

参考文件速查

登录后查看全文
examples