Nunjucks includes in markdown can lead to strange formatting

[mikemonteith]

With eleventy, we can include nunjucks code inside markdown.

This gives us benefits in that we can write our component documentation mostly in markdown, but still include design examples via nunjucks. The issue is that the output from nunjucks is then being parsed by markdown. Depending on whitespace, HTML coming from nunjucks templates can sometimes get wrapped by <p> tags in unwanted places.

Consider the following markdown file:

This is markdown

{% include "test.njk" %}

test.njk file:

{# test.njk #}

<div>
  <div>
    <div>

      Some html

    </div>
  </div>
</div>

This will result in an output of:

<p>This is markdown</p>
<div>
  <div>
    <div>
<p>Some html</p>
<p></div></p>
  </div>
</div>

Usually, if we are writing HTML in nunjucks, we don't want it's output to be sent through markdown. This is an issue in some places, which we are working around by manipulating the indentation, but it results in ugly source templates.

This issue could cause headaches further down the line.