Eleventy 博客首篇文章实战解析front matter 配置、Nunjucks 布局与代码高亮全流程【免费下载链接】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本篇技术指南以当前仓库framework-boilerplates/eleventy目录中的 firstpost.md 为核心骨架系统讲解 Eleventy 静态站点生成器中一篇博客文章从 Markdown 源文件到最终 HTML 页面的完整生命周期。你将掌握front matter 元数据如何驱动标题、日期与标签渲染posts目录数据文件的集合机制Nunjucks 布局模板与标签过滤器的协作方式以及如何在 Markdown 正文中嵌入可高亮显示的代码块。文中所有结论均可在本仓库对应文件中找到源码佐证可直接对照学习。一、关联文档概览一篇最小的 Eleventy 博客文章firstpost.md 是仓库内 Eleventy 样板项目源自eleventy-base-blog中的第一篇示例文章全文件仅 26 行却完整覆盖了一篇 Eleventy 博客文章的全部关键要素YAML front matter定义标题、描述、日期、标签与布局Markdown 正文包含多段正文与二级标题带语言标注的代码块演示代码高亮插件的效果。该文件位于 posts 目录下与secondpost.md、thirdpost.md、fourthpost.md共同构成站点文章集合。它是一篇元示例——不仅自身是博客内容其 front matter 结构与仓库中 base.njk 等模板对元数据的消费方式相互印证是理解 Eleventy 数据流的最佳入门素材。二、front matter一篇文章的元数据协议2.1 逐字段拆解 firstpost.md 的 YAML 头firstpost.md 顶部 8 行是标准 YAML front matterEleventy 会将其解析为文章页面的data对象--- 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文章标题被 post.njk 渲染为h1{{ title }}/h1同时被 base.njk 用作title标签无标题时回退到metadata.titledescription页面描述被 base.njk 写入meta namedescription有利于 SEOdate文章发布日期经过滤器格式化后显示在文章页time标签中tags文章标签用于构建文章集合与标签页也会以链接形式渲染在文章头部layout使用的布局模板指定 layouts/post.njk该布局自身又继承layouts/base.njk注意date使用了2018-05-01这种日期字符串格式。仓库 .eleventy.js 中定义了两个日期过滤器来消费它readableDate输出dd LLL yyyy格式如01 May 2018htmlDateString输出yyyy-LL-dd格式如2018-05-01二者均在 post.njk 中被使用。2.2 front matter 与其他数据层的合并机制front matter 只是 Eleventy 数据级联Data Cascade中的一层。以本文为例最终页面的数据由以下来源按优先级合并目录数据文件posts/posts.json 为posts目录下的所有文章注入tags: [posts]——这正是firstpost.md的 front matter 中只写another tag却仍能进入文章集合的原因front matter 本身文章级字段title、date、layout等全局数据文件metadata.json 提供站点级配置站点名、描述、feed 路径等在布局模板中通过metadata.title、metadata.feed.path等方式访问。三者的协作在 base.njk 中清晰可见页面标题优先取文章自己的title没有则回退到metadata.titleRSS 与 JSON Feed 链接则直接引用metadata全局数据。三、正文与代码块Markdown 与 Nunjucks 的混合处理3.1 正文中的 Markdown 结构firstpost.md 的正文由两段样板占位文字和一个二级标题## Section Header组成。这些内容是eleventy-base-blog模板自带的占位文案Lipsum 式文本仅用于演示一篇完整文章的排版效果实际建站时应替换为自己的内容。3.2 代码块如何触发语法高亮文件末尾的代码块使用了带语言标注的围栏式写法 text/2-3 // this is a command function myCommand() { let counter 0; counter; } // Test with a line break above this line. console.log(Test);其中 text/2-3 是 PrismJS 风格的语言别名表示以 text 语言高亮。仓库 [.eleventy.js](https://link.gitcode.com/i/39efdd919ff75245d51a883b96c2d061) 注册了 11ty/eleventy-plugin-syntaxhighlight 插件该插件在构建时会把 Markdown 中的代码块转换为带 language-* 类的 precode 结构样式则由 [base.njk](https://link.gitcode.com/i/35f31ab7a3a8188de24c515b34875986#L9) 引入的 [prism-base16-monokai.dark.css](https://link.gitcode.com/i/18984c7ecec38af48affb4d2a1dd21bf) 提供。换句话说作者只需在 Markdown 中标注语言高亮主题与类名生成全部由插件自动完成。 此外[.eleventy.js](https://link.gitcode.com/i/33563e7b749c333bbefa961c2d3b7531) 还通过 markdown-it 定制了 Markdown 渲染行为开启 html: true允许内联 HTML、breaks: true换行转为 br、linkify: true自动识别 URL并叠加 markdown-it-anchor 为标题自动生成带 # 符号的可点击锚点链接。 ## 四、布局链与集合机制文章如何变成页面 ### 4.1 双层布局链 firstpost.md 的 layout: layouts/post.njk 触发一条布局继承链 1. **post.njk**[文章布局](https://link.gitcode.com/i/e4ca961db7725eb0b151e89d32e5c43a)其 front matter 声明 layout: layouts/base.njk 与 templateClass: tmpl-post正文区渲染文章标题 h1、经 htmlDateString/readableDate 过滤的 time 日期标签、由 filterTagList 过滤后的标签链接以及 {{ content | safe }} 输出的正文 HTML 2. **base.njk**[基础布局](https://link.gitcode.com/i/35f31ab7a3a8188de24c515b34875986)提供完整的 HTML5 骨架、CSS 引入、基于 eleventyNavigation 的顶部导航以及通过 {{ content | safe }} 嵌入子布局的输出。 post.njk 还使用 getNextCollectionItem / getPreviousCollectionItem来自 [.eleventy.js](https://link.gitcode.com/i/f5c92256ab9b20d7064810093490fa89) 引入的 11ty/eleventy-navigation 插件在 collections.posts 中定位上一篇/下一篇生成文章底部的导航链接。 ### 4.2 posts 集合的构建 posts 集合的来源是双重的 - [posts/posts.json](https://link.gitcode.com/i/16be114b9485b89bb7788a5ab4621a78) 为目录下所有文章注入 tags: [posts] - front matter 中 layout: layouts/post.njk 与标签共同决定文章进入文章集合与标签集合。 [.eleventy.js](https://link.gitcode.com/i/f5c92256ab9b20d7064810093490fa89#L48-L62) 中的 filterTagList 过滤器会剔除 all、nav、post、posts 等内部标签只保留作者自定义的标签如 firstpost 中的 another tag用于展示与构建标签页tagList 集合则汇总全站所有可见标签。这也解释了为什么 firstpost.md 的标签渲染结果中不会出现 posts。 ## 五、把文章跑起来本地构建与开发调试 [README.md](https://link.gitcode.com/i/b72f83f0adbec8d674248cd469ba4981) 提供了完整的上手流程本仓库 [package.json](https://link.gitcode.com/i/6bd466ade0fefc9894456eb329821083) 已预置对应 npm 脚本 bash # 1. 安装依赖Eleventy 1.x 与相关插件 npm install # 2. 修改 _data/metadata.json替换为你的站点信息 # 标题、URL、描述、feed 路径与作者信息 # 3. 一次性构建输出到 _site 目录 npx eleventy # 或 npm run build # 4. 本地开发启动本地服务器并监听文件变更自动刷新 npx eleventy --serve # 或 npm run serve / npm start # 5. 仅监听文件变更并重新构建不启动服务器 npx eleventy --watch # 或 npm run watch # 6. 调试模式输出详细构建日志 DEBUG* npx eleventy # 或 npm run debug构建行为由 .eleventy.js 的返回值控制templateFormats声明处理md/njk/html/liquid四种模板markdownTemplateEngine与htmlTemplateEngine均设为njk意味着 Markdown 正文与 HTML 模板都会先经过 Nunjucks 预处理——这正是 firstpost.md 正文中可以直接书写{{ }}模板语法的前提dir指定输入根目录、_includes布局目录、_data数据目录与_site输出目录pathPrefix则用于站点部署在子目录时修正链接。同时addPassthroughCopy(img)与addPassthroughCopy(css)会把静态资源原样复制到输出目录。六、从 firstpost 出发扩展一篇文章的通用套路对照同目录的 secondpost.md 与 fourthpost.md可以总结出在posts目录下新增文章的标准范式新建 Markdown 文件声明title、description、date、tags、layout: layouts/post.njkposts.json 会自动补上posts标签正文按 Markdown 语法撰写代码块标注语言即可自动高亮HTML 内容在html: true配置下可直接混排运行npx eleventy --serve即可在本地预览文章会出现在首页文章列表与标签页中由 postslist.njk 等模板驱动。值得一提的是front matter 并非只能写在 Markdown 文件中——仓库中 about/index.md 展示了内容页的写法而 Eleventy 支持在任意模板格式Markdown、Nunjucks、HTML、Liquid中书写 front matter只要文件位于输入目录且未在 .eleventy.js 的templateFormats中排除即可被处理。七、小结firstpost.md虽然只是一篇占位示例文章却是理解 Eleventy 数据流与渲染管线的理想切片front matter 提供页面级数据目录级 posts.json 与全局级 metadata.json 分层补充双层 Nunjucks 布局负责结构呈现Markdown 经markdown-it与语法高亮插件转换为带锚点与代码高亮的 HTML最终由 .eleventy.js 的目录配置输出到_site。掌握这套从一篇 Markdown 文件到一个完整博客页面的链路即可在本样板项目基础上快速搭建自己的静态博客。【免费下载链接】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），仅供参考 Eleventy 博客首篇文章实战解析：front matter 配置、Nunjucks 布局与代码高亮全流程
Eleventy 博客首篇文章实战解析front matter 配置、Nunjucks 布局与代码高亮全流程【免费下载链接】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本篇技术指南以当前仓库framework-boilerplates/eleventy目录中的 firstpost.md 为核心骨架系统讲解 Eleventy 静态站点生成器中一篇博客文章从 Markdown 源文件到最终 HTML 页面的完整生命周期。你将掌握front matter 元数据如何驱动标题、日期与标签渲染posts目录数据文件的集合机制Nunjucks 布局模板与标签过滤器的协作方式以及如何在 Markdown 正文中嵌入可高亮显示的代码块。文中所有结论均可在本仓库对应文件中找到源码佐证可直接对照学习。一、关联文档概览一篇最小的 Eleventy 博客文章firstpost.md 是仓库内 Eleventy 样板项目源自eleventy-base-blog中的第一篇示例文章全文件仅 26 行却完整覆盖了一篇 Eleventy 博客文章的全部关键要素YAML front matter定义标题、描述、日期、标签与布局Markdown 正文包含多段正文与二级标题带语言标注的代码块演示代码高亮插件的效果。该文件位于 posts 目录下与secondpost.md、thirdpost.md、fourthpost.md共同构成站点文章集合。它是一篇元示例——不仅自身是博客内容其 front matter 结构与仓库中 base.njk 等模板对元数据的消费方式相互印证是理解 Eleventy 数据流的最佳入门素材。二、front matter一篇文章的元数据协议2.1 逐字段拆解 firstpost.md 的 YAML 头firstpost.md 顶部 8 行是标准 YAML front matterEleventy 会将其解析为文章页面的data对象--- 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文章标题被 post.njk 渲染为h1{{ title }}/h1同时被 base.njk 用作title标签无标题时回退到metadata.titledescription页面描述被 base.njk 写入meta namedescription有利于 SEOdate文章发布日期经过滤器格式化后显示在文章页time标签中tags文章标签用于构建文章集合与标签页也会以链接形式渲染在文章头部layout使用的布局模板指定 layouts/post.njk该布局自身又继承layouts/base.njk注意date使用了2018-05-01这种日期字符串格式。仓库 .eleventy.js 中定义了两个日期过滤器来消费它readableDate输出dd LLL yyyy格式如01 May 2018htmlDateString输出yyyy-LL-dd格式如2018-05-01二者均在 post.njk 中被使用。2.2 front matter 与其他数据层的合并机制front matter 只是 Eleventy 数据级联Data Cascade中的一层。以本文为例最终页面的数据由以下来源按优先级合并目录数据文件posts/posts.json 为posts目录下的所有文章注入tags: [posts]——这正是firstpost.md的 front matter 中只写another tag却仍能进入文章集合的原因front matter 本身文章级字段title、date、layout等全局数据文件metadata.json 提供站点级配置站点名、描述、feed 路径等在布局模板中通过metadata.title、metadata.feed.path等方式访问。三者的协作在 base.njk 中清晰可见页面标题优先取文章自己的title没有则回退到metadata.titleRSS 与 JSON Feed 链接则直接引用metadata全局数据。三、正文与代码块Markdown 与 Nunjucks 的混合处理3.1 正文中的 Markdown 结构firstpost.md 的正文由两段样板占位文字和一个二级标题## Section Header组成。这些内容是eleventy-base-blog模板自带的占位文案Lipsum 式文本仅用于演示一篇完整文章的排版效果实际建站时应替换为自己的内容。3.2 代码块如何触发语法高亮文件末尾的代码块使用了带语言标注的围栏式写法 text/2-3 // this is a command function myCommand() { let counter 0; counter; } // Test with a line break above this line. console.log(Test);其中 text/2-3 是 PrismJS 风格的语言别名表示以 text 语言高亮。仓库 [.eleventy.js](https://link.gitcode.com/i/39efdd919ff75245d51a883b96c2d061) 注册了 11ty/eleventy-plugin-syntaxhighlight 插件该插件在构建时会把 Markdown 中的代码块转换为带 language-* 类的 precode 结构样式则由 [base.njk](https://link.gitcode.com/i/35f31ab7a3a8188de24c515b34875986#L9) 引入的 [prism-base16-monokai.dark.css](https://link.gitcode.com/i/18984c7ecec38af48affb4d2a1dd21bf) 提供。换句话说作者只需在 Markdown 中标注语言高亮主题与类名生成全部由插件自动完成。 此外[.eleventy.js](https://link.gitcode.com/i/33563e7b749c333bbefa961c2d3b7531) 还通过 markdown-it 定制了 Markdown 渲染行为开启 html: true允许内联 HTML、breaks: true换行转为 br、linkify: true自动识别 URL并叠加 markdown-it-anchor 为标题自动生成带 # 符号的可点击锚点链接。 ## 四、布局链与集合机制文章如何变成页面 ### 4.1 双层布局链 firstpost.md 的 layout: layouts/post.njk 触发一条布局继承链 1. **post.njk**[文章布局](https://link.gitcode.com/i/e4ca961db7725eb0b151e89d32e5c43a)其 front matter 声明 layout: layouts/base.njk 与 templateClass: tmpl-post正文区渲染文章标题 h1、经 htmlDateString/readableDate 过滤的 time 日期标签、由 filterTagList 过滤后的标签链接以及 {{ content | safe }} 输出的正文 HTML 2. **base.njk**[基础布局](https://link.gitcode.com/i/35f31ab7a3a8188de24c515b34875986)提供完整的 HTML5 骨架、CSS 引入、基于 eleventyNavigation 的顶部导航以及通过 {{ content | safe }} 嵌入子布局的输出。 post.njk 还使用 getNextCollectionItem / getPreviousCollectionItem来自 [.eleventy.js](https://link.gitcode.com/i/f5c92256ab9b20d7064810093490fa89) 引入的 11ty/eleventy-navigation 插件在 collections.posts 中定位上一篇/下一篇生成文章底部的导航链接。 ### 4.2 posts 集合的构建 posts 集合的来源是双重的 - [posts/posts.json](https://link.gitcode.com/i/16be114b9485b89bb7788a5ab4621a78) 为目录下所有文章注入 tags: [posts] - front matter 中 layout: layouts/post.njk 与标签共同决定文章进入文章集合与标签集合。 [.eleventy.js](https://link.gitcode.com/i/f5c92256ab9b20d7064810093490fa89#L48-L62) 中的 filterTagList 过滤器会剔除 all、nav、post、posts 等内部标签只保留作者自定义的标签如 firstpost 中的 another tag用于展示与构建标签页tagList 集合则汇总全站所有可见标签。这也解释了为什么 firstpost.md 的标签渲染结果中不会出现 posts。 ## 五、把文章跑起来本地构建与开发调试 [README.md](https://link.gitcode.com/i/b72f83f0adbec8d674248cd469ba4981) 提供了完整的上手流程本仓库 [package.json](https://link.gitcode.com/i/6bd466ade0fefc9894456eb329821083) 已预置对应 npm 脚本 bash # 1. 安装依赖Eleventy 1.x 与相关插件 npm install # 2. 修改 _data/metadata.json替换为你的站点信息 # 标题、URL、描述、feed 路径与作者信息 # 3. 一次性构建输出到 _site 目录 npx eleventy # 或 npm run build # 4. 本地开发启动本地服务器并监听文件变更自动刷新 npx eleventy --serve # 或 npm run serve / npm start # 5. 仅监听文件变更并重新构建不启动服务器 npx eleventy --watch # 或 npm run watch # 6. 调试模式输出详细构建日志 DEBUG* npx eleventy # 或 npm run debug构建行为由 .eleventy.js 的返回值控制templateFormats声明处理md/njk/html/liquid四种模板markdownTemplateEngine与htmlTemplateEngine均设为njk意味着 Markdown 正文与 HTML 模板都会先经过 Nunjucks 预处理——这正是 firstpost.md 正文中可以直接书写{{ }}模板语法的前提dir指定输入根目录、_includes布局目录、_data数据目录与_site输出目录pathPrefix则用于站点部署在子目录时修正链接。同时addPassthroughCopy(img)与addPassthroughCopy(css)会把静态资源原样复制到输出目录。六、从 firstpost 出发扩展一篇文章的通用套路对照同目录的 secondpost.md 与 fourthpost.md可以总结出在posts目录下新增文章的标准范式新建 Markdown 文件声明title、description、date、tags、layout: layouts/post.njkposts.json 会自动补上posts标签正文按 Markdown 语法撰写代码块标注语言即可自动高亮HTML 内容在html: true配置下可直接混排运行npx eleventy --serve即可在本地预览文章会出现在首页文章列表与标签页中由 postslist.njk 等模板驱动。值得一提的是front matter 并非只能写在 Markdown 文件中——仓库中 about/index.md 展示了内容页的写法而 Eleventy 支持在任意模板格式Markdown、Nunjucks、HTML、Liquid中书写 front matter只要文件位于输入目录且未在 .eleventy.js 的templateFormats中排除即可被处理。七、小结firstpost.md虽然只是一篇占位示例文章却是理解 Eleventy 数据流与渲染管线的理想切片front matter 提供页面级数据目录级 posts.json 与全局级 metadata.json 分层补充双层 Nunjucks 布局负责结构呈现Markdown 经markdown-it与语法高亮插件转换为带锚点与代码高亮的 HTML最终由 .eleventy.js 的目录配置输出到_site。掌握这套从一篇 Markdown 文件到一个完整博客页面的链路即可在本样板项目基础上快速搭建自己的静态博客。【免费下载链接】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），仅供参考