Troubleshooting

While following along the notes in the previous sections some questions arise. Let’s clear some of them.

Various Issues

How to start using raw html in markdown files.

How to insert a new line in markdown.

(Solving #1 using as an example to solve #2.)
Goal : In markdown the way to insert line breaks (without that horrible sea of white space around) but just want to start from a new line, is to use double space.
Problem : The text editor or its plugins might strip the double space to one space, leaving you without a line break.
Solution : Use html <br/>. By default Hugo will not allow to use raw html in markdown. To enable, add to hugo.yaml (standard practice if you are the only author of your content):

markup:
  goldmark:
    renderer:
      unsafe: true

Getting a specific version of Hugo

1. E.g.getting Hugo v0.121.2
   Download this Hugo version binary from Github releases repository Downloaded this one e.g.: hugo_extended_0.121.2_Linux-64bit.tar.gz

2. Unzip (just double click on it).
   Unzips into a folder e.g. ~/Downloads/hugo_extended_0.121.2_Linux-64bit.
   cd into the containing folder.
   In there there will be three files: license, readme and the executable hugo binary.
3. Rename that binary from hugo to name+whatever version you chose to download, e.g. hugo1212
4. Move or copy the renamed executable to /usr/local/bin. (Check if /usr/local/bin is in your path by running echo $PATH, but it most likely is.) Copying:

~/Downloads/hugo_extended_0.121.2_Linux-64bit$
sudo cp -i hugo1212 /usr/local/bin/hugo1212

(By using -i for interactive you will be asked if you would like to replace the file.)

5. That’s it, set up your Hugo project as usual and use instead of hugo server -> hugo1212 server (all other hugo commands likewise).

To submodule or not to submodule.

To submodule
Using a theme as a submodule is recommended by theme developers in their docs. And it is a good way to go. And that’s what was used in the deploy section of this “Hugo Guide”.
But submodules are great if:

• The theme author relentlessly looks after his/her project, i.e. the theme. That is keeps up to date with every new release of Hugo.

Not to submodule
These are open source commercial-free projects and it is often that the theme project authors stop updating their themes to stay inline with Hugo updates.
Then consider:

• not to submodule a theme
• use a specific version of hugo for this theme

This can be a fallback option. If a theme stops being supported, it is good to know that it will not break your project. Just revert to a specific hugo version when the project worked. (Alternatively you could modify the theme yourself.)

How submoduling effects deployment with GitHub Actions
In no way.
You specify to use a submodule in hugo.yaml.
.github/workflows/hugo.yaml does not care if you use submodules. Submodules will be downloaded when the workflow runs the hugo command which builds the /public dir of site. And that command either downloads submodules specified in hugo.yaml or uses themes folder.

U+003E error

If getting this error unrecognized character in shortcode action: U+003E '>' but you did close all the }}. Make sure you have in hugo.yaml:

enableInlineShortcodes: true

Hugo shortcodes execute even if they are inside code blocks.

Use this notation (wrap in /* */) to prevent a shortcode from executing (when want to just document):

{{</* foo */>}}
{{%/* bar */%}}

Will render without /* */:

{{< foo >}}
{{% bar %}}

• Shortcodes with opening and closing tags too:

{{</* callout */>}}
Some text.
{{</* /callout */>}}

• Note, escaping shortcodes will not work inside another shortcode. E.g. inside hugo theme hextra callout shortcode. Hugo will throw an error.

Link to a page on the current site

Use Hugo built-in shortcodes (in markdown):
[Deploy]({{< ref "/docs/deploy" >}})
In comparison, to link to an outside page in markdown:
[Deploy](https://example.com).

CSS

The theme might be perfect but as you start customizing it, things may start to look not so perfect.
To fix how your changes look on a webpage, create inside dir asstet, dir css, file custom.css (name of the file might be specific to your chosen theme). And place all your desired CSS fixes there.

Fix sticking elements

When creating several badges on the landing page (the home page), they appear to stick together. (In development they show up ok, stick in production.)
Add this to assets/css/custom.css:

#badge_container::after {
  overflow: hidden;
  width: auto;
  display: inline;
  clear: both;
  content: "";
  display: table;
}

.badge_elem {
  float: left;
  margin-right: 0.5em;
}

::after is to clear the float used in .badge_elem (otherwise the badges will float over the text that follows, on narrow screens).

Use the defined CSS in content/_index.md:

<div id="badge_container">
    <div class="badge_elem">
    {{< hextra/hero-badge >}}
    <!--badge 1 content-->
    {{< /hextra/hero-badge >}}
    </div>

    <div class="badge_elem">
    {{< hextra/hero-badge >}}
    <!--badge 2 content -->
    {{< /hextra/hero-badge >}}
    </div>

</div>