Demonstration HUGO site

Sunday, Mar 7, 2021
Tags: HUGO markdown

Contents

So when I revamped this site I decided to convert from a Wordpress generated site to a site generated by a static site generator. Why? With Wordpress I was not taking care of the environment. Wordpress overtime has updated the codebase for security and new feature reasons. I did not keep up so the site went dark.

After several false starts over the years I came across a video series from Mike Dane on creating a web site using the HUGO static site generator. From this I researched other resources to get a better understanding of HUGO and its capabilities. I’m still learning, however in this post I will go over the steps that you can take to create a basic blog web site.

The requirements for this Demo Hugo site are to create a basic site to demonsrate how HUGO can be used to quickly produce a site with static html pages. The site will consist of a Home page, an About page, a page listing blog posts and the post themselves.

Ok, so lets create a web site.

Prepare folders

To start we will need folders for our code.

  1. Create a HUGO folders
  2. In the HUGO folder create a bin sub folder.
C:\>md HUGO

C:\>cd HUGO

C:\HUGO>md bin

Install HUGO

Next we need to download the HUGO code that will allow us to create our website.

  1. In a browser go to the following url https://github.com/gohugoio/hugo/releases

  2. Scroll to the down to downloads section, select the appropriate download file. At time of writing for myself this was hugo_0.80.0_Windows-64bit.zip.

  3. Extract the downloaded zip file into the C:\Hugo\bin folder

  4. In a Command Prompt window change to the folder C:\Hugo\bin

  5. From the command line run the following

    C:\Hugo\bin>hugo version

If Hugo is working then a message will be displayed with the Hugo version. At the time of writing I had the following displayed

    C:\Hugo\bin>hugo version
    Hugo Static Site Generator v0.80.0-792EF0F4 windows/amd64 BuildDate: 2020-12-31T13:37:57Z
  1. For Hugo commands to run from other folders it is necessary to Hugo to be added to the PATH.

    1. In the search bar enter environment
    2. Select the Edit the system environment variables from the Control Panel
    3. This will display a System Properties dialog
    4. Select Environment variables to display the Environment variables dialog.
    5. From the System variables list, select Path and then click Edit to display the Edit environment variable
    6. Click on New and enter C:\Hugo\bin
    7. Click OK
    8. Click OK
    9. Click OK
  2. You are now ready to create your first web site using HUGO.

Create a new site

Now it is time to create our first web site using HUGO.

  1. Open a Command Prompt window and naviagate to the Hugo folder.
  2. Run the following command
    C:\Hugo>hugo new site demo-hugo-site
  1. A message is then displayed indicating that the site has been set up
  2. Change to the C:\Hugo\demo-hugo-site folder and enter dir and the following will be displayed.
     Directory of C:\Hugo\demo-hugo-site

    02/15/2021  01:57 PM    <DIR>          .
    02/15/2021  01:57 PM    <DIR>          ..
    02/15/2021  01:57 PM    <DIR>          archetypes
    02/15/2021  01:57 PM                82 config.toml
    02/15/2021  01:57 PM    <DIR>          content
    02/15/2021  01:57 PM    <DIR>          data
    02/15/2021  01:57 PM    <DIR>          layouts
    02/15/2021  01:57 PM    <DIR>          static
    02/15/2021  01:57 PM    <DIR>          themes
  1. Now enter the following
   C:\Hugo\demo-hugo-site>hugo server -D
  1. Open a browser to the following url localhost:1313
  2. A blank page will be display, but this is the web site. Now to start adding some content.

Create basic layout

Template

To start our web site I created a template for how I want the pages to look like.

This is just a basic html page with the following code. From this files for the HUGO site will be created.

<html>
<head>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
    <meta name="description" content="Template site to demonsrate HUGO created by Steve Watts">
    <meta name="keywords" content="HUGO">
    <title>Demo Hugo Site</title>
    <style>
        body {
            background-color: white;
        }

        h1 {
            color: black;
        }

        a.menuLink, a.menuLink:hover, a.navRef, a.navRef:hover, a.footerRef, a.footerRef:hover {
            text-decoration: none;
            color: white;
        }

        .titleCol {
            text-align: center;
            height: 75px;
            padding: 1px;
            text-transform: capitalize;
            background-color: #218221;
            color: white
        }

        #titleRef, #titleRef:hover, #titleRef:visited {
            text-decoration: none;
            color: white;
        }

        #navBar {
            background-color: #218221;
            text-align: center;
            padding: 1px;
            font-size: medium;
        }

        #content {
            background-color: white;
            min-height: 400px;
            padding: 10px;
        }

        .footerRow {
            height: 70px;
        }

        #footer {
            color: white;
            background-color: #218221;
            bottom: 0px;
            text-align: center;
            height: 70px;
            padding: 5px;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="row">
            <div class="col-md-12, titleCol">
                <h1><a id="titleRef" href="/">Demo Hugo Site</a></h1>
            </div>
        </div>
        <div class="row" id="navBar">
            <div class="col-md-1" id="navBar">
                <a class="menuLink" href="/">Home</a>
            </div>
            <div class="col-md-1" id="navBar">
                <a class="menuLink" href="/posts">Blog</a>
            </div>
            <div class="col-md-1" id="navBar">
                <a class="menuLink" href="/about">About</a>
            </div>
            <div class="col-md-9" id="navBar">
                &nbsp;
            </div>
        </div>
        <div class="row" id="content">
            <div class="row">
                <div class="col-md-12">
                    <h1 id="welcome">Welcome</h1>
                    <p>
                        Thank you for your interest in my HUGO tutorial.<br>
                        This is the template page and the final result my be different.<br>
                        Enjoy
                    </p>

                </div>
            </div>
        </div>
        <div class="row" id="footerRow">
            <div class="col-md-12" id="footer">
                <p>Demo Hugo Site</p>
                <a href="http://www.codingwithanaccent.com" class="footerRef" target="_blank">Created By Coding With An Accent</a>
            </div>
        </div>
    </div>
</body>
</html>


Head code

HUGO allows for code to be broken into components which allows for code to be written once and used in different places.

  1. In order to do this navigate to the web site folder and then to the layouts folder.
  2. In this folder create 2 sub folders, _default and partials.
C:\Hugo\demo-hugo-site\layouts>md _default

C:\Hugo\demo-hugo-site\layouts>md partials
  1. It is in the partials folder that we will create the components needed for this project.
  2. Create a text file in the C:\Hugo\demo-hugo-site\layouts\partials folder called head.html
  3. Open the head.html in a text editor. I’m using VS Code.
  4. Add the following text to the file and Save.
<head>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
    <meta name="description" content="Template site to demonsrate HUGO created by Steve Watts">
    <meta name="keywords" content="HUGO">
    <title>Demo Hugo Site</title>
    <style>
        body {
            background-color: white;
        }

        h1 {
            color: black;
        }

        a, a:hover {
            text-decoration: none;
            color: black;
        }
        a.menuLink, a.menuLink:hover, a.navRef, a.navRef:hover, a.footerRef, a.footerRef:hover {
            text-decoration: none;
            color: white;
        }

        .titleCol {
            text-align: center;
            height: 75px;
            padding: 1px;
            text-transform: capitalize;
            background-color: #218221;
            color: white
        }

        #titleRef, #titleRef:hover, #titleRef:visited {
            text-decoration: none;
            color: white;
        }

        #navBar {
            background-color: #218221;
            text-align: center;
            padding: 1px;
            font-size: medium;
        }

        #content {
            background-color: white;
            min-height: 400px;
            padding: 10px;
        }

        .footerRow {
            height: 70px;
        }

        #footer {
            color: white;
            background-color: #218221;
            bottom: 0px;
            text-align: center;
            height: 70px;
            padding: 5px;
        }
    </style>
</head>

Header code

The next componet is the header for the web page.

  1. In the C:\Hugo\demo-hugo-site\layouts\partials folder create a text file called header.html
  2. Open the header.html in a text editor.
  3. Add the following text to the file and Save.
<div class="row">
	<div class="col-md-12, titleCol">
		<h1><a id="titleRef" href="/">Demo Hugo Site</a></h1>
	</div>
</div>
<div class="row" id="navBar">
	<div class="col-md-1" id="navBar">
		<a class="menuLink" href="/">Home</a>
	</div>
	<div class="col-md-1" id="navBar">
		<a class="menuLink" href="#">Blog</a>
	</div>
	<div class="col-md-1" id="navBar">
		<a class="menuLink" href="#">About</a>
	</div>
	<div class="col-md-9" id="navBar">
		&nbsp;
	</div>
</div>

The next componet is the footer for the web page.

  1. In the C:\Hugo\demo-hugo-site\layouts\partials folder create a text file called footer.html
  2. Open the footer.html in a text editor.
  3. Add the following text to the file and Save.
        <div class="row" id="footerRow">
            <div class="col-md-12" id="footer">
                <p>Demo Hugo Site</p>
                <a href="http://www.codingwithanaccent.com" class="footerRef" target="_blank">Created By Coding With An Accent</a>
            </div>
        </div>

List page

Now that we have our components for web pages the next step is to create the templates for the pages. For this project we will create a list template and a single template. The list template renders content from multiple sources into a single web page. The single template renders specific content.

  1. Navigate to the C:\Hugo\demo-hugo-site\layouts_default folder and create a text file called lists.html
  2. Open the lists.html in a text editor.
  3. Add the following text to the file and Save.
<html>
{{ partial "head" . }}
<body>
    {{ partial "header" (dict "Kind" .Kind "Template" "List") }}
    <div class="contentRow">
    Lists template</br>
    {{.Content}}
    </div>
    {{ partial "footer" . }}
</body>
</html>

Single page

Now we shall create the single template

  1. Navigate to the C:\Hugo\demo-hugo-site\layouts_default folder and create a text file called single.html
  2. Open the single.html in a text editor.
  3. Add the following text to the file and Save.
<html>
{{ partial "head" . }}
<body>
    {{ partial "header" (dict "Kind" .Kind "Template" "Single") }}
    <div class="contentRow">
    Single template</br>
    {{.Content}}
    </div>
    {{ partial "footer" . }}
</body>
</html>

Create Home page

Our next step is to create a home page with some content.

  1. In the command prompt navigate to the web site root folder C:\Hugo\demo-hugo-site.
  2. Enter the following command
C:\Hugo\demo-hugo-site>hugo new _index.md
  1. This will result in a file named _index.md being created in the C:\Hugo\demo-hugo-site
  2. Open the _index.md file in a text edit and the following contents will be seen
    ---
    title: ""
    date: 2021-02-15T17:44:58-05:00
    draft: true
    ---
  1. Now enter the following text so that the contents are as follows
    ---
    title: ""
    date: 2021-02-15T17:44:58-05:00
    draft: true
    ---
    # Welcome
    Thank you for your interest in my HUGO tutorial.
    This is the template page and the final result my be different.
    Enjoy

Test the Website

Now that we have some inital content its time to see the results.

  1. From the command prompt run the following command
C:\Hugo\demo-hugo-site>hugo server -D
  1. This will start to run the HUGO server and the following will be output
Start building sites …

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

Built in 17 ms
Watching for changes in C:\Hugo\demo-hugo-site\{archetypes,content,data,layouts,static}
Watching for config changes in C:\Hugo\demo-hugo-site\config.toml
Environment: "development"
Serving pages from memory
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
  1. In a browser go to the following URL, http://localhost:1313/ to view the site

Localhost:1313

Note: To stop the server, press Cntl+C

Create About page

Now that we have the Home page the next step will be to add an About page.

  1. From the Comand Prompt
  2. Enter the following command
C:\Hugo\demo-hugo-site>hugo new about\_index.md
  1. This will create a new sub folder under the content folder with a file called _index.md.
  2. Open the _index.md file in a Text editor and it will contain something
    ---
    title: "About"
    date: 2021-02-21T08:29:35-05:00
    draft: true
    ---
  1. Content can now be added to this file for the page.
---
title: "About"
date: 2021-02-21T08:29:35-05:00
draft: true
---

This is the about page

  1. Save the file
  2. Now go to the header.html file and modify the navigation script for the About link

	<div class="col-md-1" id="navBar">
		<a class="menuLink" href="/about">About</a>
	</div>

  1. Save the header file
  2. Rerun the HUGO server and review the site.

Create Blog posts

The next task will be to add a blog to the we site. This can be achieved with the addition of a few lines of code and a new sub folder in the content directory.

Modify the html pages

To see the blog posts the list.html and header.html files need to be modified.

  1. In a text editor modify the list.html file as follows.

<html>
{{ partial "head" . }}
<body>
<div class="container" >
    {{ partial "header" (dict "Kind" .Kind "Template" "List") }}
    <div class="row" id="content">
	    <div class="row">
		    <div class="col-md-12" style="margin:5px; padding:5px;">
			    {{.Content}}
		    </div>
        </div>
        {{ range .Pages }}
        {{ if eq .Params.type "post" }}
        <div class="row">
            <div class="col-md-12" style="border: 1px solid black; margin:5px; padding:5px;">
                <div class="row">
                    <div class="col-md-12" style="font-size:20px;">
                        <a href="{{.URL}}">{{.Title}}</a>
                    </div>
                </div>
                <div class="row">
                    <div class="col-md-12" style="color:grey; font-size:16px;">
                        {{ dateFormat "Monday, Jan 2, 2006" .Date }}
                    </div>
                </div>
                <div class="row" style="font-size:18px;">
                    <div class="col-md-12">
                        {{.Summary}}
                    </div>
                </div>
            </div>
        </div>
        {{ end }}
        {{ end }}
    </div>
    {{ partial "footer" . }}
</div>
</body>
</html>

  1. In the text editor modify the header.html file as follows

<div class="col-md-1" id="navBar">
		<a class="menuLink" href="/posts">Blog</a>
	</div>

Create Posts

In this section we will create the 2 blog posts.

  1. From the command prompt run the following commands to create the post pages.
C:\Hugo\demo-hugo-site>hugo new posts\post1.md

C:\Hugo\demo-hugo-site>hugo new posts\post2.md


  1. This will create a posts sub folder under the content folder and in the sub folder will be 2 files post1.md and post2.md.
  2. In the text editor open the post1.md file.
  3. Modify the text as follows and save.
---
title: "The Gettsburg Address"
date: 2021-02-21T13:54:32-05:00
draft: true
type: post
summary: "Abraham Lincoln's Gettsburg Address, 1863"
---
Abraham Lincoln, 1863

Fondly do we hope, fervently do we pray, that this mighty scourge of war may speedily pass away. Yet, if God wills that it continue until all the wealth piled by the bondsman’s two hundred and fifty years of unrequited toil shall be sunk, and until every drop of blood drawn with the lash shall be paid by another drawn with the sword, as was said three thousand years ago, so still it must be said “the judgments of the Lord are true and righteous altogether.”

With malice toward none, with charity for all, with firmness in the right as God gives us to see the right, let us strive on to finish the work we are in, to bind up the nation’s wounds, to care for him who shall have borne the battle and for his widow and his orphan, to do all which may achieve and cherish a just and lasting peace among ourselves and with all nations. 
  1. Now in the text editor open the post2.md file.
  2. Modify the text as follows and save.
---
title: "The Decission to go to the Moon"
date: 2021-02-21T13:56:48-05:00
draft: true
type: post
summary: J F Kennedy's speech setting the goal for the United States to go to the moon. 1961
---
J F Kennedy, 1961

We choose to go to the moon. We choose to go to the moon in this decade and do the other things, not because they are easy, but because they are hard, because that goal will serve to organize and measure the best of our energies and skills, because that challenge is one that we are willing to accept, one we are unwilling to postpone, and one which we intend to win, and the others, too.

Note that these files have 2 additional front matter tags. The summary is used by the list.html page to display text describing the post contents. This is optional. The type is a custom tag that I created so that only post summaries would be displayed on the blog index page.

Testing the finished site

Now we have a Homepage, an About page and some blog posts so

  1. From the command prompt run the following command
C:\Hugo\demo-hugo-site>hugo server -D
  1. In your browser enter the URL localhost:1313 to view the site.

Publishing the site

Publishing a site generated by HUGO is simple.

  1. From the HUGO site folder run the HUGO command.
  2. Now if you run a folder listing you will see a Public folder.
  3. Copy the contents of the Public folder to your web server. How this is done will depend on your hosting solution and your preference.

Note:

  • It is a good practice to delete the Public folder before you run the HUGO command.
  • Publishing the website to a hosting solution will be covered in a future post.

Conclusion

In this post I have gone through the steps to create a basic web site using the HUGO static site generator. Granted the site will not win any design awards. The site does satisfy the requirements. It has a Home page, a Blog, and an About page.

I am still learning about the capabilitities of HUGO and Markdown so overtime I will write further posts. These are some of the next steps under consideration:

  • Deploy site to a web server.
  • Move style to a external style sheet.
  • Convert the layout to a theme so that others could use it in their sites
  • Modify the site to use a third party theme.
  • Explore other features and functionality of HUGO e.g. Shortcodes

If you have followed along this far. Thank you. Should you want to review and use the code for the site you can download it from my GitHub repository.

Resources

(C)2014-Today  Coding With An Accent