Display Template Markers in Hugo
The problem
It turned out to to be rather difficult to document some of the changes I’ve been attempting to implement using the hugo shortcodes. I didn’t see any reference to documentation about how to escape the shortcode markers, and it took a few hours of searching to find a suitable solution.
When I started to document some of the changes I made for a syntax highlighting article, for instance how the following is implemented:
makefile_dir := $(abspath $(shell pwd))
publish_dir := $(makefile_dir)/../boundedinfinity.github.io
list:
@grep '^[^#[:space:]].*:' Makefile | grep -v ':=' | grep -v '^\.' | sed 's/:.*//g' | sed 's/://g' | sort
bootstrap:
brew tap Homebrew/bundle
brew bundle
bower install
edit:
hugo server --buildDrafts --watch
view:
hugo server --watch
purge:
rm -rf public/
publish:
@make purge
hugo --quiet
rsync -a --delete --exclude-from .rsyncignore public/ $(publish_dir)/
cd $(publish_dir) && git add . && git commit -m "update" && git push origin master
git add . && git commit -m "update" && git push origin master
generate:
hugo --theme=$(theme)
I noticed that the {{< and >}}
got interpreted by the template engine.
I tried the normal things like preceeding the {{ with a \, and doubling up
the curly braces {{{{ which didn’t work. I re-read the templating and
shortcode documentation and didn’t see a documented way to escape the markers.
Searching for the solution
I then noticed that the shortcode documentation displayed the markers in their documentation. I think when to github and found the source for the page: /docs/content/content-management/shortcodes.md.
It seems that the propery way to accomplish this is to wrap the template markers
as normal using the {{< and >}}
markers then to wrap the content inside the markers with comment markers, /*
and */.
It worked!
So the (unwieldy) syntax is to wrap the code with:
{{</* and */>}} An example:
{{< highlight html >}}
<html>
<body>
This is an HTML example.
</body>
</body>
{{< /highlight >}}
The meta-issue
I then noticed while trying to write this article that documenting the solution also had the same issue as documenting the markers, they were interpreted by the template engine.
Since this was a meta-problem, I decided to solve it with an inception-like meta-solution. I create a shortcode to print the shortcode markers. I created the following short codes:
{{- printf "{{" -}}
{{- printf "}}" -}}
At least this bit of yak shaving had a satisfying conclusion.