A test post to see if the new blog is working, also handy for checking out themes. You really want to look at the source for this page.

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Basic Formatting

Hugo uses Github Flavoured Markdown.

• *This is italic* This is italic
• **this is bold** this is bold
• ***this is bold-italic*** this is bold-italic
• ~~this is strikethrough~~ this is strikethrough

You can do a link like this: [link](https://github.com/philipdaniels)

You can comment stuff out like this (note you may have to separate the {{ sigil:

<!--
[Link to another post]({ {< ref "post/2016/windows-vm-setup/index.md" >}})
[Link to a heading]({ {< relref "#my-normalized-heading" >}}).
-->

The horizontal rule is made with 3 or more dashes.

Images

See content organization.

Images in the same folder as the post

An image link is created by putting an exclamation mark before the link such as ![house](../house.gif)

The .. is needed because in the final site, the post’s index.html file is one folder below the images (this is due to ‘.html’ elimination from the URLs).

Images for a post in their own subfolder

The above observations lead us to a solution. Create a disk structure like this:

hugo-cheatsheet.md                  (the post)
hugo-cheatsheet/                    (a directory with the same name as the post)
hugo-cheatsheet/image1.gif          (one or more images)
hugo-cheatsheet/celtic-knot.jpg

And then in the post file hugo-cheatsheet.md you can link to an image like this

![Celtic knot](celtic-knot.jpg)

You will end up with this disk structure in your public folder:

blog\2019\hugo-cheatsheet                   (directory for the post)
blog\2019\hugo-cheatsheet\index.html        (the body of the post)
blog\2019\hugo-cheatsheet\image1.gif        (the images)
blog\2019\hugo-cheatsheet\celtic-knot.jpg

Links in index.html will be relative:

<img src="celtic-knot.jpg" alt="Celtic knot" />

Which means you can move the website around without any problems.

You can also use the figure shortcode, which allows you to set the caption and/or title.

Syntax Highlighting

fn main() -> Result<(), io::Error> {
    // This is done with a 'highlight' short code and includes highlights of lines 2 and 6-7.
    let x = 3;
    println!("Hello {}", x);

    let x = vec![1,2,3];
    let max = x.iter().max();
}

static Main() -> Result<(), io::Error> {
    // This is done with a code fence.
    let x = 3;
}

Both of these are done with highlight.js because Hugo’s built in syntax highlighting doesn’t seem to work reliably (wraps line when it shouldn’t, doesn’t select the correct theme…). See config.toml for some highlight.js parameters.

Raw HTML

You can just add raw HTML markup straight into the markdown file.

More Formatting

This is a quote

Can be on more than one line

Use 4 spaces to create pre-formatted text:

$ some example text with <b> tags </b>

Lists and Tables

A list is created using asterisks or dashes

• First
• Second
• Third

Nested and numeric lists are possible

1. First

• Sub 1
• Sub 2

2. Second

• Sub 1
• Sub 2

Another example

1. Make my changes
2. Fix bug
3. Improve formatting
   • Make the headings bigger
4. Push my commits to GitHub
5. Open a pull request

• Describe my changes
• Mention all the members of my team
  • Ask for feedback

Tables work (note the escaping of the ‘|’ character):

Hugo Commands

• New blog post (draft): hugo new blog/2019/my-title.md
• Serve (with drafts): hugo server -D
• Serve with particular theme: hugo server --theme=my-theme
• Build it: hugo

Theme Customization

(TODO: This is out of date)

Theme customization is achieved by dropping a custom file in a path in the main directory that corresponds to the path in the theme directory; typically the templates constituting the theme will have includes of the partial already. For example, I have customized Greyshade by creating files in blog/layouts/partials/custom that correspond to the files in themes/hugo-greyshade/layouts/partials/custom. I have achieved CSS customization by creating static/css/pd.css with some override styles.