Reference-style links don't work inside Markdown shortcodes

[MaxIhlenfeldt]

Bug Report

Environment

Zola version: v0.19.2

Expected Behavior

Reference-style links inside Markdown shortcodes using references defined outside of the shortcode generate an HTML link with the correct target.

Current Behavior

Reference-style links inside Markdown shortcodes using references defined outside of the shortcode generate output like this: [link text][target].

Step to reproduce

Create a shortcode note.md with the following content:

<aside>
    <p>{{ body | markdown(inline=true) | safe }}</p>
</aside>

and use it in content/page.md like this:

{% note() %}
    [Text][link]
{% end %}

[link]: https://example.com

[MaxIhlenfeldt]

By the way, I also don't understand why I need to use the markdown filter in the shortcode definition even when using a Markdown shortcode.

[harrymkt]

Issue 1 (link)

Use like this, note, follow line break:

{% note() %}
Paragraph 1

Paragraph 2

Check out [example][example] for more
{% end %}

[example]: https://example.com

Issue 2(markdown filter)

note.md (follow line break):

<aside>

{{ body }}

</aside>

[Keats]

By the way, I also don't understand why I need to use the markdown filter in the shortcode definition even when using a Markdown shortcode.

You don't. Why do you use it?

[MaxIhlenfeldt]

@harrymkt thanks, that does indeed resolve both issues - the reference-style links work now and I don't need the markdown filter any more.

I'm now using this shortcode definition, with the filename being note.md:

<aside>
<p>

{{ body }}

</p>
</aside>

I investigated a bit more and found out that the issue I was experiencing before is more nuanced. When I change the contents of note.md back to this:

<aside>
<p>
{{ body }}
</p>
</aside>

Reference-style links and markdown features like italics, backticks being turned into <code> blocks, etc. don't work only for the first paragraph. i.e. this page content:

{% note() %}
Paragraph 1

Check out [`example`][example] for more
{% end %}

[example]: https://example.com

works as expected, but this content:

{% note() %}
Check out [`example`][example] for more
{% end %}

[example]: https://example.com

Gets rendered as Check out [`example`][example] for more.

[MaxIhlenfeldt]

Addition to the above comment: if I change the contents of note.md to this:

<aside>
<p>
{{ body | markdown(inline=true) | safe }}
</p>
</aside>

i.e. use the markdown filter, markdown features like italics, backticks being turned into blocks, etc. work for the first paragraph again, but reference-style links still don't work.

[harrymkt]

In short, in order for the shortcode to know it passes as markdown, you need to add line break before and after it.

<aside>
<p>

{{ body }}

</p>
</aside>

For readability I think you should use div tag because the content itself will have many paragraph tags.

<aside>
<div>

{{ body }}

</div>
</aside>

HTH!

[MaxIhlenfeldt]

In short, in order for the shortcode to know it passes as markdown, you need to add line break before and after it.

That is super unexpected, though. Would it be difficult to fix that? If not, it should at least be in the docs - well, Markdown shortcodes should be in the docs in general 😅 I might be able to find the time to add a doc PR if that would be welcome?

For readability I think you should use div tag because the content itself will have many paragraph tags.

It actually looks the same in the end, but you're right, wrapping it in an extra <p> leads to weird HTML. I just dropped that tag, I don't think I need a div to hold all the paragraphs.

[harrymkt]

That is super unexpected, though. Would it be difficult to fix that?

I don't think it would be difficult. However, it is not unusual to put blank line break before and after it which makes the markdown parser clear, in fact this is done only 1 time in the shortcode so I don't think it'd be a problem after all. I previously used Hugo and I think that extra is not required, I don't exactly remember though. Of course, Zola's documentation isn't mentioned.

Another thing is that Zola will likely decline the feature request if that is not necessary because not to make it complicated like Hugo, but I don't know if the one you're talking about is possible the contributors might implement it, in which case they would participate in this discussion.

it should at least be in the docs - well, Markdown shortcodes should be in the docs in general 😅 I might be able to find the time to add a doc PR if that would be welcome?

Of course yeah, they would welcome all contributions.

I just dropped that tag, I don't think I need a div to hold all the paragraphs.

Of course if you don't add the div tag the content will end up inside another paragraph, which is, as the documentation suggests.

[Keats]

Looking at your examples, it seems you don't actually want markdown shortcodes? You're wrapping the body in HTML which means the commonmark parser is going to view the whole thing as HTML and not process anything in there.

[MaxIhlenfeldt]

it seems you don't actually want markdown shortcodes

Well, I'm looking for a way to have markdown styling and reference-style links work in shortcodes. I don't really care which type of shortcode I use for that. I got the styling to work in HTML shortcodes (using the markdown filter), but the references seem to only work in Markdown shortcodes. So I think I do want Markdown shortcodes?

You're wrapping the body in HTML which means the commonmark parser is going to view the whole thing as HTML and not process anything in there.

But the Markdown content I put inside the shortcode in my content does get rendered? At least if I have the line breaks around {{ body }}.