Basic Usage

Create a Site

At the commandline or command prompt, type the following:

hugo new site mysite

substituting “mysite” with your chosen site name or whatever you want to name it.

Hugo will then make a directory that will contain all of the files and folders to run a basic site.

The content for your site will be in the “content” folder and you will use markup and html to create them.

Choose and Install a Theme

You will choose a theme for your site to use as a template for your desired look and feel. See here for more info on templates

Go here Hugo Themes to pick out a theme.

Once you have chosen a theme, you will need to “install” it, by either manually putting it in the themes directory or cloning it.

Cloning Your Theme

Go to where the theme is stored

https://github.com/koirand/pulp.git

Click “clone or download theme”

Copy the web url ie https://github.com/koirand/pulp.git

If you haven’t already, initialize your site directory with git.

git init

Using the “pulp” theme as an example

git clone https://github.com/koirand/pulp.git themes/pulp

Adding Your Theme as Submodule

Instead of just cloning your theme, you can add it as a submodule. The positive of this, is you would have the potential to automatically/maually update the theme.

git submodule add https://github.com/koirand/pulp.git themes/pulp

Manually Adding Your Theme

Go to where the theme is stored

https://github.com/koirand/pulp

Click on “clone or download”

Choose “download zip”

Go to where the theme downloaded, and unzip it

For this example, the extracted folder is named “pulp-master”.

Copy the extracted folder to the themes directory.

Add Content to Your Site

The content of each page for your site is in the form of a .md file located in the content folder (your-site/content/).

Markup is used to format the pages, as well as html.

You can use hugo to make the .md files for your site pages/posts.

Dillinger Markdown Editor

Markdown Cheatsheet

Already have a site?

Use one of these sites to convert your html to markdown:

• HTML-TO-MARKDOWN
• Turndown
• Mr.42

Don’t want to use a theme? Convert your site to a theme: Convert Existing Site to Hugo Theme

Archetype Information

Each .md file in the content folder will have information at the top about that page/post that looks similar to this:

---
title: "The Title"
date: the-date-here
draft: true
---

The title is the page’s/post’s title. The date is the date and time the page/post was created. “draft” means the page/post is a draft, and will need to be changed later for production. There are other pieces of information that can go there, like menu information, tags, and more.

Most themes will have a basic archetype set that is included with yur theme.

Using Hugo to Add Content

hugo new posts/my-first-post.md

Will create a post called my-first-post.

Open up that page with your chosen editor (the following example is commandline and nano with the linux OS):

cd content/posts/
nano my-first-post.md

or

nano content/posts/my-first-post.md

Build Your Site

To build your hugo site, at the commandline or command prompt, in the site directory, type

hugo

The command hugo generates the files for your website in the “public” folder by default. You can specify the “output directory” by changing the “publishDir” field in the config file.

S4 uses the “public” folder by default. If you choose to use another, please let us know, so we can make the necessary changes.

There are options to that command, and can be found here: hugo command.

Another option is to type

hugo help

Deploy Your Site

To deploy your site, type the following command in your site directory

hugo server

There are many options available for that command. hugo server command

On your desktop, you can see the changes live while hugo is running your site, as it has “live reload”. If you want the latest rendition of your site deployed to S4, you will need to run the “hugo” command first before pushing your files to the repo,