I recently stumbled upon HTML5’s details element and wanted to use it in Jekyll. Here’s how I did it.

Intro

I mostly write in Markdown, so I could just write plain HTML:

<details>
  <summary>Read more about that **thing**...</summary>
  That **thing** is...
</details>

However, there are two reasons not to use details like this:

1. The details element is not supported by every browser, so we need some kind of a fallback.
2. The text in details and summary is not processed by Jekyll’s markup converter, so the text would be rendered as is, i.e. “Read more about that **thing**”, which is not what we want.

Polyfill

To address the first point, we can use a polyfill. I chose jquery-details, which, as the name suggests, depends on jQuery. Since I didn’t use jQuery until then, I decided to give Zepto a try, which is basically a lightweight jQuery.

I included Zepto and jquery-details in the footer of my page like this:

<script src="/js/zepto.min.js"></script>
<script>jQuery = Zepto;</script>
<script src="/js/jquery.details.min.js"></script>
<script>$('details').details();</script>

The above lets jquery-details run over every details element it finds and polyfills support for it, if necessary.

Markup Processing

The second point can be addressed by adding a custom plugin. Jekyll uses Liquid as templating engine. In Liquid you can define custom tags and even tag blocks. We can create a custom tag block to mimic the semantics of the details element and use it like this:

{% details Read more about that **thing**... %}
  That **thing** is...
{% enddetails %}

To create the new tag block, you just put the following tag block implementation in a .rb-file in Jekyll’s plugin folder:

Jekyll will automatically recognize the plugin and it is ready to use.

Styling

I added some custom SCSS to make the result appear good in different browsers. The basic functionality works without, but the styling doesn’t really suggest what’s going on.

details {
    summary {
        &::before {
            font-family: FontAwesome;
            font-size: 1.2em;
            content: "\f152";
            float: left;
            margin-right: 0.4em;
        }
        &::-webkit-details-marker {
            display: none;
        }
        margin-bottom: 0.8em;
    }
    &.open, &[open] {
        summary::before {
            content: "\f150";
        }
    }
    color: grey;
}

Result

Coming full circle, now when we write this:

{% details Read more about that **thing**... %}
  That **thing** is...
{% enddetails %}

This is what Jekyll (and your browser) renders: