Welcome to my tutorial.

The goal of my tutorial is to show what I did to get my Hugo theme up and running in the hopes you can use these instructions to do the same with the theme of your choice.

Before continuing, here the list your requirements you need to fullfil in order to make it to the end:

  • Linux running with access to the internet.
  • A home folder with enough space available for hugo, usually 1Gb is more than enough.
  • Sudo rights on your linux.
  • Updated package database. 
      sudo apt-get update
  • Hugo installed with version compatible with the theme of your choice.

Should you require help with the last topic, just take a look in my previous post Installing Hugo on Ubuntu 18.04 LTS over WSL

Step 1. Git. Yes, git!

This tutorial will use git, so if you don’t have installed yet, please do:

  sudo apt-get install git

The reason why we are going to use git is because most of the themes issue updates that may interest you along the way, so should you decide, you’ll be able to have access to these updates using a single git update instead of going through new downloads and setups.

First thing is to make a repository for yourself. For that you need to start from the folder that holds your site on hugo.

If you don’t have yet run hugo, then you can run the commands below to create your new site named “my-awesome-site”:

  cd ~
  mkdir sites
  cd sites
  hugo new site my-awesome-site

You will get the following message on your bash:

Congratulations! Your new Hugo site is created in /home/rmc/sites/my-awesome-site.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

There you go. Now, let us see a preview of your work so far.

  cd my-awesome-site
  sudo hugo

You will have the following output:

                   | EN
-------------------+-----
  Pages            |  3
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

This means you’re on the right path. Off course, so far there is not much content, but you can take a look into http://localhost:1313/ in order to check your page. Just don’t worry about its content, for the moment.

Now go back to the linux prompt and press Ctrl+C to stop hugo server. We still have work to do.

Now we have to create a git repository for your new “my-awesome-site”.

  git init

Initialized empty Git repository in /home/rmc/sites/my-awesome-site/.git/

Then add files and folders into your repository. These will have their content under version control, so be sure to add stuff that you are subject to changes that cannot be automatically re-generated once changed.

My advice is to start with the basics, concerning a new hugo site:

  git add config.toml
  git add content
  git add resources
  git add layouts
  git add static

Then make your first commit.

  git commit -m 'First commit of my-awesome-site'

Great! Now we can proceed to installing the theme.

Step 2. Installing the theme

Now we arrive to the fun part.

As stated in the Step 1, we will install Hello-Friend-NG, but should you want to take a look on all available Hugo themes, just click here

Normally, the themes available for Hugo are self explanatory, but the reason I find my tutorial useful is because these themes somehow assume you have a certain familiarity with the whole system and just skip essential parts for a great many number of people that are not.

So, let us move forward to the installation.

If you need more info about Hello-Friend-NG Hugo theme, just click here .

From within your home site folder “/home/your-user/sites/my-awesome-site” , run:

  git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng

This will download Hello-Friend-NG Hugo theme as a submodule of your site repository.

You will obtain the output:

Cloning into '/home/your-user/sites/my-awesome-site/themes/hello-friend-ng'...
remote: Enumerating objects: 43, done.
remote: Counting objects: 100% (43/43), done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 1346 (delta 20), reused 21 (delta 5), pack-reused 1303
Receiving objects: 100% (1346/1346), 6.40 MiB | 4.14 MiB/s, done.
Resolving deltas: 100% (717/717), done.

Git submodules are great if you don’t plan to make changes on the theme itself so you can always benefit from theme upgrades whenever you want to use them.

After, adding Hello-Friend-NG Hugo theme, we must turn into the instructions.

We must then, change the default config.toml file content in order to get your site up and running with this theme.

The best way to do it, is to take directly from the exampleSite.

  cd ~/sites/my-awesome-site/themes/hello-friend-ng/exampleSite
  cp config.toml ~/sites/my-awesome-site/

Then, we just get the content from the exampleSite.

  cd ~/sites/my-awesome-site/content
  mkdir posts
  cd posts
  cp -r ~/sites/my-awesome-site/themes/hello-friend-ng/exampleSite/content/posts/*.* .
  cd ..
  cp -r ~/sites/my-awesome-site/themes/hello-friend-ng/exampleSite/content/about.md .
  cd ~/sites/my-awesome-site
  sudo chown -R your-user:your-user-group resources/
  cd ~/sites/my-awesome-site/resources/_gen/assets
  cd ~/sites/my-awesome-site
  hugo server -t hello-friend-ng

Open your site on your browser .

And that is all. Press Ctrl+C to stop the server and get back to linux prompt.

There is some basic info you can change on config.toml in order to customize your site, but that is theme-dependent. I invite you to dive into it.

I leave you with some last useful complementary info:

  • The information that will appear on your home page comes from config.toml.

  • Once server hugo is launched, it is able to re-render existing pages on the fly. If you need to create a new page, just put a new .md file into ~/sites/my-awesome-site/content/posts, and restart hugo.

  • Images should be put into ‘static’ folder. If you want to a suggestion to organize and use your images:

    To organize:

      mkdir ~/sites/my-awesome-site/img

    And to use it in your pages:

    {{< image src="/img/image-name.png" alt="Alternative test to show if image does not exist." position="center" style="border-radius: 8px;" >}}

  • To show code that should remain unescaped (not interpreted by hugo), just wrap your code like this: {{< code >}}, but remember to remove pre and pos {{< >}} from your code.

  • To make links to external sites to be open in a new browser tab, do the following:

    • Go and create a file named render-link.html into ~/sites/my-awesome-site/layouts/_default/_markup.
    • Inside this file, just put:
        <a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank"{{ end }}>{{ .Text }}</a>
    • Save the file. Restart Hugo by pressing Ctrl+C and launching it again.
    • When you wish to use it, just remember that external links must start with http while local links are referred by a local path. For instance: 
        [External link to Windows Terminal](https://devblogs.microsoft.com/commandline/introducing-windows-terminal/)

  [Local link to another post](/posts/2020/03/installing-hello-friend-ng-on-hugo/).

  • Emojis? Yes, please.

    Just insert the emoji tag you want from webfx emoji-chat-sheet

  • Should you ever need full urls instead of links to folders using Hello-Friend-NG, you should proceed as follows:

    • Open you config.toml and add uglyurls = true right before the very first section on your config file, in my case it was right before [permalinks] section.
    • On section [menu], right next to the end of your config file, you must change the about and post as follows:
    [menu]
      [[menu.main]]
          identifier = "contact"                   #
          name       = "Contact"                   # Use this instead of about
          url        = "contact/contact.html"      #
      [[menu.main]]
          identifier = "posts"
          name       = "Posts"
          url        = "posts.html"                # Specify this file as it appears on the root of your output folder that would be *public* for installations without customizations.

  • On /home/yourUser/sites/yourAwesomeSite/content, create a folder “contact” and move about.md into “contact” folder, then rename about.md into contact.md.

  • Open contact.md file and remove the following from its Front Matter: aliases = [“about-us”,“contact”], you can just comment the line, by placing a # on its first column.

    # aliases = [“about-us”,“contact”]

If you want, you can still make a new git commit, now that you have everything up and running.

  git commit -m 'First commit after Hello-Friend_NG is installed and running.'

As always, the best way to learn something is to play with it.

So, have fun!

Well… perhaps not true for birth control, though. 😆