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

Eleventy 博客文章编写实战从 firstpost.md 的 Front Matter 到 Vercel 零配置部署【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercelEleventy11ty是一个以模板语言无关著称的静态站点生成器本仓库的 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 的头部第 18 行是标准的 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 namedescription对 SEO 与社交分享卡片至关重要。未设置时Eleventy 会回退使用全局metadata.description。date文章发布日期。Eleventy 会将此日期作为page.datepost.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 之后是文章正文第 926 行由三个自然段加一个## 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.postsindex.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/asecondpost.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 relalternate、顶栏导航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 Mattertitle、description、dateISO 格式、自定义tags并指定layout: layouts/post.njk正文使用标准 Markdown 撰写代码块标注语言以启用语法高亮运行npx eleventy --serve本地预览检查标题、日期、标签链接与上一篇/下一篇导航修改 _data/metadata.json 中的站点名称、描述与 Feed 配置首次部署时必做提交代码推送到仓库由 Vercel 自动执行eleventy构建并发布。通过 posts.json 的目录级标签注入新文章无需任何额外配置即可自动出现在首页列表、归档页、标签页与 RSS/JSON Feed 中——这正是以 firstpost.md 为范本的 Eleventy 内容工作流最实用之处。【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考