Eleventy 博客文章编写实战：从 firstpost.md 的 Front Matter 到 Vercel 零配置部署-开发者社区

Eleventy 博客文章编写实战：从 firstpost.md 的 Front Matter 到 Vercel 零配置部署

【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel

Eleventy（11ty）是一个以"模板语言无关"著称的静态站点生成器，本仓库的 examples/eleventy 目录提供了一个可以直接部署到 Vercel 的完整博客示例，而 firstpost.md 正是这个博客的第一篇示例文章。本文将以该文件为骨架，逐层拆解一篇 Eleventy 博客文章从 Front Matter 配置、Markdown 正文、模板布局渲染，到本地构建与 Vercel 部署的完整链路，读完你就能独立编写、组织并发布自己的 Eleventy 博客文章。

一、firstpost.md 在示例博客中的位置与作用

firstpost.md 位于 examples/eleventy/posts/firstpost.md，它是eleventy-base-blog模板自带的演示文章。围绕它，示例目录中还配套了以下关键文件：

posts/posts.json：目录级数据文件，为 posts 目录下所有文章统一注入tags: ["posts"]；
_includes/layouts/post.njk：文章页布局模板；
_includes/layouts/base.njk：全站 HTML 骨架；
_includes/postslist.njk：文章列表复用组件；
_data/metadata.json：全局站点元数据；
index.njk：首页，按时间倒序展示最新文章。

在 Eleventy 中，Markdown 文件（以及 Nunjucks、Liquid、HTML 等任意受支持模板）都可以作为内容源。firstpost.md 的正文虽然只是占位文案，但它完整示范了"一篇内容页该写什么、怎么写"：文件头部的 YAML Front Matter 负责元数据与渲染配置，文件体部的 Markdown 负责内容本身，二者共同决定这篇内容最终如何被构建成 HTML。

二、Front Matter：文章的元数据与渲染配置

firstpost.md 的头部（第 1～8 行）是标准的 YAML Front Matter，它既是文章的元数据声明，也是 Eleventy 的模板数据入口：

--- title: This is my first post. description: This is a post on My Blog about agile frameworks. date: 2018-05-01 tags: - another tag layout: layouts/post.njk ---

各字段的作用与解析方式如下：

title：文章标题。它会被 base.njk 渲染进<title>{{ title or metadata.title }}</title>，同时被 post.njk 渲染成页面<h1>{{ title }}</h1>，还会出现在首页文章列表的链接文本中（见 _includes/postslist.njk 的post.data.title）。
description：文章摘要。base.njk 第 7 行将其输出为<meta name="description">，对 SEO 与社交分享卡片至关重要。未设置时，Eleventy 会回退使用全局metadata.description。
date：文章发布日期。Eleventy 会将此日期作为page.date，post.njk 通过readableDate过滤器格式化为可读日期、htmlDateString输出到<time datetime>属性；首页列表 _includes/postslist.njk 同样依赖它排序和展示。示例博客使用 luxon 驱动这些日期过滤器。
tags：文章标签。firstpost.md 打上了another tag，同时因为 posts.json 的统一注入，它自动获得posts集合标签——这正是该文章能进入博客文章集合的原因（详见下一节）。标签会渲染为指向/tags/<slug>/的链接（post.njk），配合 tags.njk 与 tags-list.njk 生成按标签归档的页面。
layout：指定渲染该文章使用的布局模板。这里指向layouts/post.njk，其内部再通过layout: layouts/base.njk链式套用到全站骨架，形成"内容 → 文章布局 → 全站布局"的嵌套渲染。

补充一点：除了在每篇文章里手写tags，更常见的做法是利用目录级数据文件（posts/posts.json）为整个目录统一注入集合标签，firstpost.md 正是两者叠加生效的例子。

三、正文：Markdown 与代码块的高亮渲染

Front Matter 之后是文章正文（第 9～26 行），由三个自然段加一个## Section Header小节和一段代码组成。这段正文说明了 Eleventy 内容编写的基本形态：

普通段落直接使用标准 Markdown；
二级标题## Section Header会被构建为文章内的章节锚点；
代码块使用三个反引号包裹。示例中的text/2-3这种带语言标注的写法，会被 @11ty/eleventy-plugin-syntaxhighlight 插件识别，配合 prism-base16-monokai.dark.css 在 base.njk 中引入的 Prism 主题完成语法高亮。

Eleventy 对 Markdown 的解析通过 markdown-it 完成（见 package.json 中的markdown-it与markdown-it-anchor依赖），后者为标题自动生成锚点。最终{{ content | safe }}（post.njk）将转换后的 HTML 安全地注入布局。

需要留意的是：示例博客并非把文章局限在 Markdown 一种格式。如 README.md 所述，内容可以是任意受支持的模板语言；而css、png这类非模板类型会被原样拷贝到输出目录，保持目录结构不变。

四、文章如何进入集合：目录数据文件与 collections

一篇 Markdown 不会自动出现在博客首页，它必须进入collections.posts集合。这里的机制是：

posts/posts.json 作为目录级数据文件，为 posts/ 目录下的所有内容统一注入tags: ["posts"]；
Eleventy 会把带有相同 tag 的内容聚合为一个集合，posts标签即生成collections.posts；
index.njk 通过collections.posts | head(-3)取最近 3 篇渲染到首页，collections.posts.length用于标题中显示数量；archive.njk 则展示全部文章；
_includes/postslist.njk 是列表渲染的复用组件，按date倒序（| reverse）排列，并输出标题、日期和标签链接。

因此，只要往 posts 目录新增一篇带 Front Matter 的 Markdown（甚至无需显式写posts标签，目录数据文件会自动补上），它就会自动出现在首页、归档页和 Feed 中。secondpost.md 还展示了文章间的交叉引用写法：<a href="{{ '/posts/firstpost/' | url }}">First post</a>（secondpost.md），| url过滤器会正确处理站点的路径前缀。

五、布局渲染管线：post.njk 与 base.njk 的嵌套

firstpost.md 指定的layout: layouts/post.njk不是终点，而是一条链的首环：

post.njk 顶部继续声明layout: layouts/base.njk，负责渲染<h1>标题、日期、标签，并在正文前后通过collections.posts | getNextCollectionItem(page)/getPreviousCollectionItem(page)生成上一篇 / 下一篇导航；
base.njk 是最终的 HTML 骨架，负责<head>（标题、description、样式、Atom/JSON Feed 的<link rel="alternate">）、顶栏导航（eleventyNavigation插件）与<main>内容区；
全局数据 metadata.json 中的title、description、feed.path、jsonfeed.path等字段在 base.njk 中被大量引用，因此部署前应优先修改该文件。

这种"内容 → 文章布局 → 全站布局"的分层设计，让多篇文章共享一套外观，是 Eleventy 组合式布局的核心模式。

六、本地构建与开发：从 npx eleventy 到自动化调试

示例博客在 package.json 中封装了完整脚本，等价于 README.md 的 Getting Started 流程：

# 安装依赖 npm install # 单次构建 npx eleventy # 等价于 npm run build # 本地开发服务器（带热更新） npx eleventy --serve # 等价于 npm run start / npm run serve # 文件变更时自动重建 npx eleventy --watch # 等价于 npm run watch # 调试模式，输出详细构建日志 DEBUG=* npx eleventy # 等价于 npm run debug

其中--serve会启动一个本地 HTTP 服务器并在模板或内容变更时自动重载，--watch则仅重建不启动服务器。修改文章前，建议先npx eleventy --serve实时预览渲染结果。

七、部署到 Vercel：零配置的构建与发布

作为本仓库的示例之一，这个 Eleventy 博客可以零配置部署到 Vercel。根据 README.md 的说明，部署方式有两种：

使用 Vercel 部署按钮：一键将示例模板克隆为你的项目并直接上线；
常规流程：把项目推送到 Git 仓库后，在 Vercel 中导入项目。Vercel 会识别 package.json 中的build: eleventy脚本作为构建命令，自动完成安装依赖与静态产物输出，无需额外配置。

值得强调的是，这个示例目录刻意不包含.eleventy.js配置文件，体现了"零配置"的设计意图。如果你想自定义站点行为——例如调整 templateFormats、修改输入输出目录、注册插件——再在项目根目录添加.eleventy.js即可，Vercel 构建时会自动加载。

八、发布新文章的完整 Checklist

综合以上分析，在示例博客上发布一篇新文章的推荐步骤是：

在 examples/eleventy/posts 目录新建 Markdown 文件（如posts/my-new-post.md），命名即未来的 URL 路径；
头部写入 Front Matter：title、description、date（ISO 格式）、自定义tags，并指定layout: layouts/post.njk；
正文使用标准 Markdown 撰写，代码块标注语言以启用语法高亮；
运行npx eleventy --serve本地预览，检查标题、日期、标签链接与上一篇/下一篇导航；
修改 _data/metadata.json 中的站点名称、描述与 Feed 配置（首次部署时必做）；
提交代码推送到仓库，由 Vercel 自动执行eleventy构建并发布。