Getting phrasing-only content through Markdown intact

Support
1

I’m just learning Zola and think I’m most of the way to a basic working blog, but I’m at my wits’ end over what ought to be a trivial shortcode for a simple HTML <details> disclosure widget. This takes block content and a summary argument. The summary will sometimes contain inline markdown, such as code; the block content will sometimes contain images via the usual ![]() syntax.

My details.md template is just:

<details>
  <summary>

{{summary}} 
  </summary>

{{body}}
</details>

and I call it as

{% details(summary="Why `cargo` is nice") %}
Some optional longwinded discussion of why Cargo is nice, plus a cat.

![Cat](cat.jpg)
{% end %}

The markdown processor doesn’t seem to process markdown in the shortcode’s output unless it’s separated from the preceding HTML tag by a blank line. Without that, cargo doesn’t get rendered as code in the final page. But as soon as it is separated, it gets wrapped in a <p> by the caller’s processor, and <p> isn’t legal content for the <summary> element. The world doesn’t explode or anything, but validators complain.

I originally had this as an HTML shortcode template because I hadn’t read the docs closely enough, but this had the same problem. I had to get the summary argument as {{summary | markdown | safe}} and still got it wrapped in a <p>. Plus, in an HTML shortcode there doesn’t seem to be any way to get the unqualified co-located cat.jpg image link in the block content rewritten as absolute, meaning it’ll break in a feed context.

I’m starting to have horrible suspicions about the viability of <details> in a blog anyway, having no particular optimism that feed readers will handle it consistently, but still can’t help feeling that I’m missing something fundamental about the Zola/Markdown processing model here. Can anyone help?

Update: bypassing the shortcode and inlining everything into the content page doesn’t help either; the summary content isn’t processed:

<details>
<summary>Test `code` test</summary>
blah blah blah
</details>

So it’s looking like a Markdown/pulldown issue rather than a Zola/shortcode one. Sorry if this is now the wrong forum to be asking in, but any suggestions still much appreciated.

2

Hello, I did not read this extra extra closely yet, but here’s some advice that may help you out.

First, I think this is the right forum.

Trying using {%- and/or -%} to remove leading/trailing whitespace. This should help with you <p> issue inside the <summary> tag.

Also, piping to markdown | safe is good.

Tera, the zola templating engine, is going to quite literally substitute whatever you give it, but it can be tricky because you may include new lines in your shortcode’s code, e.g. for readability. Normally, like outside of shortcodes, this is fine, because html will ignore new lines between tags unless it’s inside a pre tag or something. However, when you mix and match the templating engine and markdown then there can be some seemingly unexpected behavior. If you combine this with sometimes piping to markdown and sometimes not, then it’s easy to get lost in the order things are being rendered and which layer of that ordering is responsible for what. Especially since markdown is whitespace sensitive.

So my advice is just be patient and control your whitespace. It is most likely something simple. Build very simple test examples if you’re unsure of how some aspect of your code is interacting with other parts. Like this you can convince yourself of either user error or that something is actually not working. It is also totally possible that bugs exist, either in tera, zola, or pulldown, but they’re obviously more rare than user error.

Btw, if you share a link to a specific commit I may be able to take a look. Without a specific commit I can’t really know for sure what’s going on.

Also, this is unrelated to zola, but I think <details> is good in a blog. It’s a very old element and so is handled very consistently across browsers. I think the one exception is different browsers have vendorized css namespaces for styling the summary triangle thingy. However, additional benefits are that it’s semantic html, so it works well for people with screen readers, and an accessible web is better for everybody in general. Also the details element works very nicely for reader mode in browsers like safari.

Hope that’s a good start.

3

Hi spence, thanks for the reply! I’ve tried adding whitespace-removal but to no effect. Same with physically removing all whitespace from inside the shortcode; that just breaks processing. It’s definitely looking like the Markdown processor won’t convert Markdown unless it’s separated from preceding raw HTML tags by a blank line.

I’ve pushed a stripped-down demonstration of my issue to GitHub - mrec/phrasing_in_details_summary

I’m all in on Team <details> Supremacy - as you say, accessibility is great and browser support is rock solid. It’s just feedreader support that worries me. At the moment I’m sticking in a <!-- more --> after the first para and pointing to the blog URL, but that doesn’t feel like a great solution.

Thanks again, whether you get a chance to look at the demo or not.

P.S. “It’s a very old element”??? I can remember <blink> and <marquee>, you young whippersnapper! :rofl:

1 Like
4

Awesome code sample to drill down into the issue. I appreciate the normal + one liner html x md matrix.

I am super busy right now but I’ll try to look into this in a few days and see if I can get the expected behavior to work.

1 Like
5

You are very close with {summary | markdown | safe}! The only thing you’re missing is that the markdown filter takes an additional optional argument: inline which defaults to false. As you observed by default the markdown processor wraps the content in <p>. Setting inline = true removes that from the output and should be the result you’re looking for. This behavior is documented here.

My implementation of this as a shortcode is the following, markdown is fully working in both the summary and the body:

<details {% if open %}open="open"{% endif %}>
    <summary>{{ title | markdown(inline = true) | safe }}</summary>
    {{ body | markdown | safe }}
</details>
1 Like
6

Aha! Very promising, thanks! I can confirm that markdown(inline=true) solves the summary problem for me in the HTML shortcode.

The only remaining issue is that, since this is an HTML shortcode, a colocated-asset image relative URL in the body block doesn’t get promoted to absolute. However, your cunning trick can work for the MD shortcode too, which doesn’t have this problem.

The magic combo seems to be:

  1. Force the summary argument to markdown with inline=true, to avoid the <p> wrapping.
  2. Leave the body as is, with an empty line within the shortcode after the <summary> so that the processor will still process it when it’s returned to the caller.
<details>
<summary>{{summary | markdown(inline=true) | safe}}</summary>

{{body}}
</details>

That solves all my problems. (Well, apart from the persistent rash and the weird chicken dreams.) Thanks again.

In other happy news, I noticed yesterday that the official Rust blog is using <details> in its feed for the Project Goals Update, so I don’t feel quite so exposed using it myself.

1 Like