s

Creating a website using Hugo



Hugo’s Getting Started guide is the place to start!

It is quite easy to get started. Once Hugo is installed is installed, you can generate a new site from the command line using the built-in command hugo new site <sitename>. This will generate all the files and directories that are needed to get going.

  • hugo new site <sitename>

hugo new site blog will create a blog directory containing the following files:

  • archetypes: Markdown templates for the various types of content such as posts, projects etc.
  • config.toml file for the configuration variables for the site.
  • content directory to hold the content for the site
  • data directory to hold data files in YAML, JSON or TOML.
  • layouts folder to define how the site will look. This folder contains templates in .html format.
  • static directory for images, CSS, JavaScript
  • themes folder to hold themes that you can create yourself or download.

The directory structure is explained on the getting started guide here.

Hugo commands

  • hugo help Once Hugo is installed you can use the hugo help command to see some help documentation. This will list the available Hugo commands and flag options. The main ones I have used so far are:

  • hugo new site <my_blog> to generate a new site directory contains files files and folders listed above.

  • hugo server to run a local development server. Go to the the localhost (usually 1313) in your browser to see the website.

  • hugo server -D Using the D flag will also include content marked as draft:true status. Any content with draft:true will not be published by default.

  • hugo to build / rebuild the site before deploying. The website will be generated to the public/ folder by default although this can be changed. The website is then ready to be deployed to a web server.

These commands are all usually run from the root of the site.

Deploying a hugo website

After running the hugo server command for local web development you need to run hugo command to rebuild the site. Hugo generates a static site which can be hosted anywhere on any web server. So far I have only used Netlify to host a site but there are other options.

The two options I have used for deploying the site so far are:

  • pushing the entire hugo folder to GitHub then configure Netlify settings to build the site.

  • Pushing just the public folder to a GitHub repository. Then deploy to Netlify.

Once the site has been setup on Netlify and linked to the Git repository you only need to push the changes to GitHub and the site will automatically be updated.

  • You can also manually drag a public folder into Netlify.

Live Reload

Hugo comes with LiveReload which is a tool for web developers and designers.
LiveReload monitors changes in the file system. As soon as you save a file, it is preprocessed as needed, and the browser is refreshed. When you change a CSS file or an image, the browser is updated instantly without reloading the page.

Running the hugo server command will run a fully functioning web server while at the same time watching the file system for additions, deletions or changes within certain parts of the site including the static, content, data, i18n, layouts, themes/current theme folders and the config file. Whenever you make changes Hugo simultaneously rebuilds the site while serving the content.

Creating Content

The command hugo new can be used to create content for the site.

  • hugo new content/_index.md to create a home page.
  • hugo new content/about.md to create an about page
  • hugo new content/contact.md to create a page called contact
  • hugo new posts/my-post.md to create a blog post in the posts section.

You can create different sections under the content folder. Some common sections might be for projects, blog posts, presentations, CV / resumé.

Configuring the Hugo site

  • The configuration section of the getting started guide provides the full list of configuration options. There are many default configurations which you don’t need to specify unless you want to change from the defaults. For example Goldmark is the current default Markdown rendering engine but you could still use the BlackFriday markdown rendering engine by setting the defaultMarkdownHandler to blackfriday in the top level markup config of the configuration file.

Here are some of the configurations from the list of all configuration settings .

  • baseURL for the hostname and path to the root

  • enableEmoji defaults to False. See Emoji cheatsheet

  • enableInlineShortcodes = true to implement shortcodes inline. This is set to false for security reasons as explained here. However for a blog website such as this where you have total control over the content it would be safe to allow inline shortcodes. See Shortcode variables.

  • enableRobotsTXTdefaults to false. Change to true to enable generations of robots.txt file.

  • footnoteReturnLinkContents for the text to display for footnote return links.

  • googleAnalytics("") to use your google analytics tracking id.

  • menu to add non content entries to a Menu. See Add Non-content Entries to a Menu. See menu-templates

  • paginate to change the default number (10) of elements per page in pagination.

  • permalinks

  • publishDir to change the directory where Hugo builds the final static site from the default which is the public directory.

  • relativeURLs to make all relative URLs relative to content root

  • theme the theme to use

  • title the site’s title.

  • uglyURLs to create URLs of the form /filename.html instead of /filename/.

Help and learning resources.

The hugo help command will list the availabe hugo commands and options.

Hugo’s getting started guide has a list of external learning resources including books and video tutorials.


Tech used:
  • JavaScript
  • CSS
  • HTML