Eleventy 中 Nunjucks 模板在 Markdown 中的空格控制问题

在 Eleventy 静态网站生成器中，开发者经常会将 Nunjucks 模板文件包含到 Markdown 文件中使用。然而，这种组合使用方式可能会产生一些意料之外的 HTML 输出格式问题，特别是关于空白字符的控制。

问题现象

当在 Markdown 文件中通过 {% include %} 标签引入一个包含循环的 Nunjucks 模板时，生成的 HTML 会出现多余的 <p> 段落标签包裹每个列表项。例如：

原始 Nunjucks 模板：

<ul>
  {% for item in items %}
    <li>{{ item }}</li>
  {% endfor %}
</ul>

生成的 HTML 输出：

<ul>
  <p><li>Item 1</li></p>
  <p><li>Item 2</li></p>
</ul>

这种输出显然不符合预期，因为 <li> 元素不应该被 <p> 标签包裹，这会破坏列表的语义结构和样式表现。

问题原因

这个问题源于 Markdown 处理器和 Nunjucks 模板引擎对空白字符处理方式的差异。Markdown 处理器会尝试将连续的文本块转换为段落，而 Nunjucks 模板中的循环结构会产生多个独立的输出块，每个块都被 Markdown 当作独立的段落处理。

解决方案

Nunjucks 提供了空白字符控制功能来解决这个问题。通过在模板标签中添加连字符(-)，可以去除标签前后的空白字符：

修正后的 Nunjucks 模板：

<ul>
  {%- for item in items %}
    <li>{{ item }}</li>
  {%- endfor %}
</ul>

这样生成的 HTML 输出就会符合预期：

<ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ul>

技术细节

Nunjucks 的空白字符控制是通过在标签中添加连字符实现的：

• {%- 表示删除标签前的所有空白字符（包括换行符）
• -%} 表示删除标签后的所有空白字符
• {%- -%} 表示同时删除标签前后的空白字符

在 Eleventy 项目中，当混合使用 Markdown 和 Nunjucks 时，特别是在循环结构中，使用这些空白控制标记可以确保生成的 HTML 结构保持整洁和预期。

最佳实践

1. 在 Nunjucks 循环结构中使用空白控制标记
2. 对于包含在 Markdown 中的复杂 Nunjucks 模板，全面检查空白字符影响
3. 在开发过程中验证生成的 HTML 结构是否符合预期
4. 对于简单的包含，可能不需要空白控制，但对于循环和条件语句则很有必要

通过理解和正确使用 Nunjucks 的空白字符控制功能，开发者可以确保 Eleventy 项目中的模板组合生成干净、符合语义的 HTML 输出。