Problem with rendered content from an include shortcode

support
1

Hey there,

We’re trying to move to using Hugo with the Docsy theme for our documentation site. A key feature we need is the ability to reuse content by including it in multiple pages. Fortunately, I found a shortcode to do exactly that from this Discourse post. I did modify it a bit to better suit us, and to also catch errors if an included flle cannot be found:

{{/* From https://discourse.gohugo.io/t/include-file-shortcode-for-including-files-with-shortcode-calls/16699 */}}
{{- $includes_dir := (.Get 1) | default .Site.Params.includes_dir -}}
{{- $include_file := printf "%s/%s" $includes_dir (.Get 0 ) -}}
{{- with .Site.GetPage $include_file -}}
  {{- .Content | markdownify -}}
{{- else -}}
{{- (errorf `%s: include shortcode could not find page named "%s"` .Position $include_file) -}}
{{- end -}}

Initially, it seems to work fine. However, we’ve noticed odd issues with included content. Drilling down into it, it turns out that some of the Markdown that included via the include shortcode is misinterpreted.

For example, when you directly view a page’s output, a code example it contains shows up like what is under the “Correct” in this image:

incorrectly-rendered-code
incorrectly-rendered-code636×871 24.1 KB

When we use the include shortcode to pull that page into another page, it seems that the Markdown rendering gets confused and interprets the result-table and the line of hyphens below it as a heading, as shown in under “Incorrect” in the image above.

I can edit the code example so that the table isn’t interpreted as a heading (i.e. by indenting the line of hyphens by one space). However, we have a very large set of documentation (over 5000 pages) with hundreds of pieces of included content. Manually tweaking each one for multiple versions of documentation is too much work.

I’ve tried multiple ways to resolve the issue. Using .RenderString instead of markdownify doesn’t change things. Using safeHTML doesn’t show the same issue. However, it does not render shortcodes. Not being able to use shortcodes within included content is a deal-breaker for us.

So, I’m at my wit’s end. I’ve created a minimal reproducer over on github. Anyone have any ideas on how to resolve this?

Thanks!

1 Like
2

Two issues:

  1. When invoking the shortcode, use the {{< xxx >}} notation instead of the {{% xxx %}} notation.
  2. In the shortcode, don’t pass .Content through markdownify — the content is already rendered.
3 Likes
3

Perfect. Those changes seem to have cleared things up. Thanks!

3 Likes
4

Thank you for sharing a complete example. That makes troubleshooting so much easier. I wish everyone did this.

2 Likes
5

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.