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

Eleventy 博文实战从 front matter 到文章集合与布局渲染——以 secondpost.md 为例【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples导读在 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 ---各字段的作用如下字段取值示例作用与说明titleThis is my second post.文章标题会被post.njk渲染为h1同时用于浏览器标题与导航descriptionThis is a post on My Blog about ...文章摘要。在 base.njk 中作为meta namedescription输出若未设置则回退到metadata.descriptiondate2018-07-04文章发布日期用于按时间排序与时间标签渲染可省略省略时以文件创建时间为准tagsnumber 2标签数组单个标签也按数组写法。该字段同时决定文章归属哪个集合layoutlayouts/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 到 HTMLpost.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 }} classpost-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 relalternate声明以及基于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 %}liNext: a href{{ nextPost.url | url }}{{ nextPost.data.title }}/a/li{% endif %} {%- if previousPost %}liPrevious: a href{{ previousPost.url | url }}{{ previousPost.data.title }}/a/li{% endif %} /ul {%- endif %}getNextCollectionItem/getPreviousCollectionItem按日期对posts集合排序自动找出当前页的相邻文章。这意味着你只需新增博文文件并写好 front matter页面间的上下篇导航就会自动生成无需手工维护。五、标签体系从博文标签到标签聚合页secondpost.md的标签是number 2firstpost.md使用another tagthirdpost.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插件标题会自动生成锚点内联 HTMLsecondpost.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 --serveEleventy 会启动本地服务并监听文件变化实时重建浏览器打开即可预览secondpost.md渲染后的文章页生产构建npm run build产物输出到_site/目录调试DEBUG* eleventy可输出详细的构建日志排查集合、数据与布局问题时非常有用。构建完成后secondpost.md会被输出为_site/posts/secondpost/下的静态 HTML同时站点首页index.njk通过_includes/postslist.njk列出全部文章、标签页、RSS/JSON Feedfeed/目录读取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【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考