The Tale of Markdownify

Simon Hanukaev — Tue, 21 Aug 2018 20:26:46 +0000

While I was playing around with Hugo and Jekyll, I found out that their markdownify filter is somewhat confusing.

To describe the problem, first I want to show you how Jekyll's markdownify filter works.

Assume you have defined my_text parameter, for example inside _config.yml file:

my_text: consectetur **adipiscing** [elit](https://www.example.com)

As you can see, this variable is a string in a markdown format. Now, let's try to use that variable inside a template file.

<div>Lorem ipsum dolor sit amet, {{ site.my_text | markdownify }}</div>

Now, if you try to generate an HTML from this template using Jekyll, you will get something like this:

<div>Lorem ipsum dolor sit amet,
  <p>consectetur <strong>adipiscing</strong>
    <a href="https://www.example.com">elit</a>
  </p>
</div>

Although this is probably not what we wanted, because the content of our variable is wrapped with  tag. It is totally predictable behaviour because markdown always wraps its content with block elements.

But in Hugo, the behaviour is less predictable:

<div>Lorem ipsum dolor sit amet, {{ .Site.Params.my_text | markdownify }}</div>

Results in:

<div>Lorem ipsum dolor sit amet, consectetur <strong>adipiscing</strong>
  <a href="https://www.example.com">elit</a>
</div>

This is actually what we wanted, but wait. What if our variable had two paragraphs?

params:
  my_text: |-
    first paragraph

    second paragraph

Now we get this:

<div>Lorem ipsum dolor sit amet,
  <p>first paragraph</p>
  <p>second paragraph</p>
</div>

Wait... but I thought Hugo was stripping these  tags. Well, not if you have more than one paragraph.

But what if I really wanted to wrap a paragraph with ? According to this thread, you should use blocks filter. But in my opinion, it is better to have some kind of inline parameter to strip out  tags rather than stripping them by default and making markdownify filter to behave incorrectly. Even if that means that we won't always get what we want. Standards are above us all :)

And what about Jekyll? Well, although there were some attempts (see this issue and this pull request) to provide an inline parameter to the markdownify filter, they didn't succeed. And I didn't find any nice way to markdownify that variable without making it being wrapped with  tag. The only solution I found is just to set the variable to raw HTML and use it without markdownify.

I think the real problem here is that markdown syntax does not define any standard way to create inline content, that wouldn't be wrapped with a block level elements such as . But if we had something like:

This will be wrapped placed inside paragraph

!!!But this **will not**!!!

That would produce:

<p>This will be wrapped with paragraph</p>

But this <strong>will not</strong>

Then it would make our lives much better.

Live long and prosper 🖖

DEV Community: Simon Hanukaev

The Tale of Markdownify