Shortcode to render markdown

support
1

I’d like to turn {{% doc "foo" %}} into [foo](path/to/foo) for starters, ideally with error checking (file doesn’t exist). I have placed my logic inside layout/shortcodes/doc.md. A basic {{ .Get 0 }} works, but the moment I try to extend this, I run into errors I don’t know how to resolve.

2

Now, it’s recommanded to write as:

{{< doc "foo" >}}

What’s the error?!
What’s the hugo version?!

3

I interpreted the docs as saying that {{< was for HTML only, whereas Markdown (being an intermediate content stage) required {{%.

The entire Hugo docs could be better imo, they assume a lot of implicit knowledge that’s Hugo-specific and there aren’t enough examples. Good as a reference (complete), not so good to get started.

I didn’t post a code snippet because I feel I don’t grasp the correct syntax, and the Errors contained no specific information beyond “build error” / line number.

Maybe I should try my luck with HTML templates, those have more examples. I just thought that feeding Markdown into the page/pipeline would be neater somehow.

4

Just to your understanding:

Since v0.55.0:

Shortcodes Revised

Shortcodes using the {{% as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.

If you want the old behavior, you can put the following line in the start of your shortcode template:

{{ $_hugo_config := `{ "version": 1 }` }}

But using the {{< delimiter will, in most cases, be a better alternative, possibly in combination with the markdownify template func.

As you can read, I’m not interpreted! :wink:

Use as I wrote into my previous reply; and use function markdownify if you want to include MD code; for HTML, you have htmlUnescape or safeHTML,…

it’s up to you!

5

Ok, switching to {{< then. Here’s a code snippet where I get stuck for example:

{{ with $a := .Get 0 }}
{{ relref . $a }}   # plain {{ $a }} works
{{ end }}

error calling relref: invalid Page received in RelRef

Hugo 0.60.1 btw, forgot to mention that.

Edit: figured that one out myself, apparently with carries the . into the scope as a value even if I do an assignment. Alternatives to expressing that (e.g. with if) welcome.

6

Perhaps, because, into shortcode, the relref function is written with only one param, as quote:

ref and relref take exactly one required parameter of reference , quoted and in position 0 .

7

I’m using the relref function, not the shortcodes, hence the required .
Are shortcodes even allowed within shortcode templates? They gave me an error too, so I switched to functions.

8

Going the raw HTML route, something like this seems to work:

{{ $d := .Get 0 }}
{{ if $d }}
<a class="doclink" href="{{ relref . $d }}">{{ $d }}</a>
{{ else }}
{{ errorf "Shortcode: {{< doc 'document' >}} missing document argument at %s" .Position }}
{{ end }}

And for Markdown, using markdownify as suggested:

{{ printf "[%s](%s)" $d (relref . $d) | markdownify }}   // line 3