The Tale of Markdownify
Tags: markdown, hugo, jekyll, markdownify
Published: 2018-08-21 20:26:46

---
title: The Tale of Markdownify
published: true
description: The behaviour of markdownify filter.
tags: markdown, hugo, jekyll, markdownify
---

While I was playing around with [Hugo](https://gohugo.io) and [Jekyll](https://jekyllrb.com/), I found out that their [`markdownify`](https://gohugo.io/functions/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:

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

As you can see, this variable is a string in a [markdown](https://daringfireball.net/projects/markdown/) format. Now, let's try to use that variable inside a template file.


```liquid
<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:

```html
<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 `<p>` tag. It is totally predictable behaviour because markdown always wraps its content with block elements.

But in Hugo, the behaviour is less predictable:

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

Results in:

```html
<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?


```yml
params:
  my_text: |-
    first paragraph

    second paragraph
```

Now we get this:

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

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

But what if I really wanted to wrap a paragraph with `<p>`? According to [this](https://github.com/gohugoio/hugo/pull/3786) thread, you should use `blocks` filter. But in my opinion, it is better to have some kind of `inline` parameter to strip out `<p>` 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](https://github.com/jekyll/jekyll/issues/3571) and [this pull request](https://github.com/jekyll/jekyll/pull/5509)) 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 `<p>` 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](https://daringfireball.net/projects/markdown/syntax) does not define any standard way to create inline content, that wouldn't be wrapped with a block level elements such as `<p>`. But if we had something like:


```markdown
This will be wrapped placed inside paragraph

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

That would produce:


```html
<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 🖖