Hugo

Sharing code in the forums

Welcome to the Hugo forums! We love building websites, and helping others do the same! And as we voluntarily discuss and support each other, it is helpful for us to show code samples.

Sharing snippets of code can sometimes be difficult, but we have a couple of handy shortcuts in Discourse (the software running these forums) to make it easier to write fancy technical-looking posts with little effort.

The secret is backticks! Also known as grave accents (spooky!), they are generally found on an English keyboard near the beginning of the number row. On my keyboard, it shares the key with tilde (~).

A backtick by itself is `.

It is also how we make sweet code blocks!

There are two ways to markup your code, inline or as a code block.

Inline code

Inline codes are useful when referencing a command, path or output from your terminal.

Example of inline backticks:

To create a new Hugo site, type `hugo new site quickstart` on the command line.

Will render as:

To create a new Hugo site, type hugo new site quickstart on the command line.

The part you are supposed to type is slightly highlighted and monotyped, to make it easier to know what is the command, and what is the instruction. This is useful in case you want to explain something you typed.

Block code

A “block” refers to a block of text, all of which needs to be shown as code. As an added bonus, if you set the language for your code sample it will provide syntax highlighting! But that is optional; using a code block is super important, so let’s keep it simple for now.

Consider the following code I want help with. If I post it to the forums it will be hard to read and understand, especially next to other text meant to be read:

{{ if .Site.Params.piwik }}

{{ end }}

Wow! That didn’t even show up correctly! Now let’s wrap it in backticks:

{{ if .Site.Params.piwik }}
<!-- Piwik -->
<script type="text/javascript">
    var _paq = _paq || [];
    /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
    _paq.push(['trackPageView']);
    _paq.push(['enableLinkTracking']);
    (function() {
        var u="//{{ .Site.Params.piwik_url | safeURL }}/";
        _paq.push(['setTrackerUrl', u+'piwik.php']);
        _paq.push(['setSiteId', '{{ .Site.Params.piwik_id | safeJS }}']);
        var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
        g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
    })();
</script>
<!-- End Piwik Code -->
{{ end }}

Okay, now we are cooking with syntactical fire!

Another (short) example, to demonstrate how to wrap your code blocks.

```
<!doctype html>
<html lang="{{ .Site.LanguageCode }}">
<head>
```

Will render as:

<!doctype html>
<html lang="{{ .Site.LanguageCode }}">
<head>

So much better!

Discourse quickbar action

There is a “quickbar” above the post window, and it has a variety of buttons to make it easy to code-up your text easily. Highlight words in a sentence or an entire block of text (it is smart enough to know which it is!) and press the button that looks like </>.

That will add the backticks, and the rest of us will suddenly realize we are troubleshooting with the real deal here, as you obviously know what you are writing about!

As a bonus, check out how to reference markdown files in your posts, such as _index.md, without turning it into a link:

2 Likes

I can also add that the backticks is the standard sign for code in markdown, it can be used in all applications that use the markdown.

Interesting! Please provide a reference to that. I was under the impression that code block with backticks was non-standard (taken from GitHub), and used on a case-by-case basis. In the original spec, code blocks are handled by indention.

I thought there were a billion versions of markdown, and am hesitant to give general advice here on anything that isn’t Blackfriday.

Inline code is standart #code, but three backticks is often used :slight_smile:

To add to that, you can even do the below to specify the language, though Discourse seems to be doing a pretty good job at auto-detecting the language:

```css
.post-date {
    /* Italicize the date stamp */
    font-style: italic;
    margin-top: -0.5em;
    margin-bottom: 0.3em;
}
```

I was able to show the triple-backquotes block above because I wrapped that with a quadruple-backticks block … like this:

````
```css
.post-date {
    /* Italicize the date stamp */
    font-style: italic;
    margin-top: -0.5em;
    margin-bottom: 0.3em;
}
```
````

And I was able to show the quadruple-backticks wrapped block as I wrapped that with quintuple-backticks block :sunglasses:

Now I am not going to show the quintuple backticks block by wrapping that with sextuple-backticks wrapping :smile:

2 Likes

I’ll add this to the “requesting help” post.

1 Like