How is the Hugo Doc site showing shortcodes in code blocks?

1

Take this as an example.

In the shortcode-template.md, the Markdown is:

### Single-word Example: `year`

Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows:

```
{{</* year */>}}
```

But in the rendered HTML, the /* and */ comment characters are auto-removed!

image

Now when I paste

```
{{</* year */>}}
```

in my site’s content file, I get:

image
image.png751×81 1.49 KB

There, those comment markers don’t get removed. So probably some JS magic is doing that? But I cannot figure out what is doing that.

1 Like
2

That is just some special “comment out shortcode” syntax I made up to make it possible to document the shortcodes. I assumed that it was just needed for the shortcode documentation, so I never documented that feature itself … But it’s no JS magic, it is the shortcode parser.

3

I don’t follow… then why isn’t it working on my site? I do hugo serve on the hugoDocs repo, and that syntax works. That syntax doesn’t work on my site… those comment characters aren’t removed.

5

I have no idea.

6

I finally figured out the problem, which can be called a subtle bug only in hugo server behavior.

If user adds an invalid shortcode, even in code blocks, hugo server fails and stops just shortcode expansion. So the localhost site serving keeps on going fine.

The issue does not become evident till the user notices the ERROR message on the terminal and runs hugo instead of hugo server.

Post with invalid shortcode

To see the issue, remove the x from {x{ in the test post markdown file, and run hugo server.

Issue

  • The website will generate fine, but with a silent error on the terminal:
    ERROR 2017/11/02 10:37:54 Unable to locate template for shortcode "img" in page "posts/src-block-hugo-shortcoded-undefined.md"
  • The hugo server run server will keep on living, and generating the pages almost correctly, while just balking on shortcode expansions!

Source and output (obviously cannot publish with the invalid shortcodes, so will need to make that one modification I mentioned above):

Post with valid shortcode

7

We had an issue about it. Some people claimed at it was a bug, but could not come up with some well defined alternative behaviour.

8

Suggestion: Possible to kill the server if that happens? User will see that the page is no longer autoloading when changes are made to the md file… and then they will check the terminal… where the reason for server kill will be clear.

9

No, that wasn’t even in the neighbourhood of what we talked about. Note that this issue is the same in regular hugo, but obviously more in your eye. Killing the server would make lots of people (me included) annoyed.

10

Can hugo introduce a warning message at the top of the generated HTML body? Some sort of banner that says “Hey, check the ERROR on terminal”, or even put out that error in the banner when running hugo server?

11

Yes, that is a good idea. Can you create a GH issue?

1 Like
12
13

Thanks for making this topic Kaushalmodi, it really saved my day when I needed to show shortcodes on the page. :slight_smile:

I know undocumented features can be removed, but I hope this ‘comment out shortcode processing’ feature remain. I, just like Kaushalmodi, found it useful.

Is it also possible to comment out the opening and closing of a shortcode separately? I couldn’t figure that out.

That means I cannot write:

We make a shortcode with {{%, then the shortcode name, and %}} after that.

Is it also possible to comment out mixed shortcodes? That’s neither something I could make work.

And so typing this currently isn’t possible:

Don’t make shortcodes by combining both approaches like so: {{< shortcode %}}.

14

I haven’t tried that exact case, but a workaround is to not use code blocks for those, and instead do {&lbrace;< shortcode %&rbrace;}. It’s ugly but might work, and hopefully you rarely need to type those :slight_smile:

15

Here’s a test case I have where I do similar to but not exactly what I suggested above: Markdown | Hugo Output.

    Search for lbrace or rbrace in the linked Markdown source.

16

What do you mean by “mixed” shortcodes? I currently see no limitation using this comment feature.

Playing with a echo shortcode like this:

{{ range (seq 0 (sub (len .Params) 1) ) }}
  {{ $.Get .  }}
{{ end }}
{{ $.Inner }}
{{ range (seq (sub (len .Params) 1) -1 0)  }}
  {{ $.Get . }}
{{ end }}

You can comment out a sequence (you give the comment start (/*) and the comment end (*/)

{{</* echo 10 11 12 />}}
{{% echo 20 21 22 %}}hello **world**{{% /echo %}}
foo bar
{{< echo 30 31 32 /*/>}}

=>

{{< echo 10 11 12 />}} {{% echo 20 21 22 %}}hello world{{% /echo %}} foo bar {{< echo 30 31 32 />}}

There you have the < and % shortcode usage both at the same time.

{{%/* echo "foo" %}}hello **world**{{% /echo */%}}

=>

{{% echo “foo” %}}hello world{{% /echo %}}

I really like this feature - how could a theme document it’s shortcodes without it?

17

Yes, and it’s not going away. I had to add it to be able to document the feature itself. I just did not thought it whould be useful to others, so I did not document it.

2 Likes
18

I’m running into an issue with this undocumented but useful feature:

{{</* res-attach "**/*.pdf" */>}}
=> ERROR message
comment ends before the right shortcode delimiter
Hugo Static Site Generator v0.38.2 linux/amd64 BuildDate: 2018-04-09T08:17:17Z

writing the shortcode documentation with:
{{</* res-attach "** /*.pdf" */>}}
looks kind of wrong to me…

19

It’s a bug, but you need to register a GitHub issue.

20

Thx, done:

21

Thx, done:

2 Likes