Some notes gained from various themes listed on https://themes.gohugo.io/themes/

To create a Hugo site use the hugo new command on the command line. This creates a skeleton of the site with a basic directory structure as well as a configuration file.

There is no default theme but plenty to choose from listed at https://themes.gohugo.io/themes.

The home page or landing page of a site is usually the first page a visitor lands on. This is the index.html page in the root directory of the website. Hugo writes files to the public/ directory so this is public/index.html.

When you run Hugo it looks for a configuration file containing settings. These settings will override the default settings. A configuration file can be TOML, YAML or JSON. Mine is called config.toml.

You write the posts in Markdown files. Hugo will convert the Markdown files into HTML.

• Markdown files are found under the content/ folder.
• Template files are found under the themes/ folder.
• The HTML files that are created are located in the public/ folder. This is the default but it can be changed in the configuration file.

When you create a new post hugo new posts/new-post.md this creates a text file called new-post.md in the posts section of the content folder. The text file has two sections. The front matter is at the top of the file and contains meta-information about the content. The front matter can be written in TOML, YAML or JSON. TOML uses +++ to surround the front matter, YAML uses ---. JSON uses curly braces {} to enclose the front matter.

The content itself is under the front matter and contains Markdown. This will be converted to HTML after the front matter has been passed into the template first. A markdown engine is used to create the HTML that is written to the output files in the public/ folder.

Template files are used to render content into HTML.

• A single template is used to render a single piece of content such as a blog post
• A list template is ised to render a group of related content such as a list of all blog posts or projects.
• A partial template is one that can be included in other templates.

There is a separate template for the homepage.

To generate HTML files for the site you run the hugo command. This will convert the markdown posts in the content section (draft=False) to HTML in the public folder. hugo server to run the built-in local web server and see it in the browser at localhost. The Web Server is available at “http://localhost:1313/” (bind address 127.0.0.1)

hugo --verbose Using the --verbose flag gives extra information INFO <date> <time> syncing static files to <my_blog/public/>

If you run the hugo server or hugo command before creating the home page or any other content then the server will just list the index.xml and sitemap.xml files.

These provide a listing of the public/ directory. Once the home page and any other content is create, going to http://localhost:1313/ will bring up the homepage. To see the listing of the public directory, add the /index.xml or sitemap.xml to see the listing. http://localhost:1313/index.xml http://localhost:1313/sitemap.xml

hugo new to create the skeleton of the site with the directory structure and empty files. The skeleton will include the template files (.html), a licence file, a theme.toml describing the theme and an empty archetype.

hugo new theme <new-theme-name> to create a new theme.

To list all the files under the theme: find themes/new-theme-name -type f | xargs ls -l

Edit the file using a code editor such as Visual Studio Code. To edit a file using the Vim editor vi with the filename. followed by the code, then :wq to save and exit the file.

vi themes/newthemename/theme.toml
whatever text
:wq

If you create a new theme you need to tell Hugo about it in the configuration file. If you don’t then you can add the -t themename to the commands but its easier to just add it to the config.toml or whatever configuration file you are using.

You also should add other meta data to the configuration file such as the baseurl, languageCode, title etc. The baseurl can be updated later when you actually have a URL for the website.

hugo --verbose to generate the site again. The message should tell you that Hugo is syncing from the theme’s directory.

ls -l public to see the files created.

There should be a home page public/index.html, acss/ folder, js/ folder. A page is a file that is created directly from a content file.

The Home page is created from the layouts/index.html template.

When the site is generated the templates are used to transform the markdown content into HTML. Static files are also copied into the site as they are. The theme folder will have folders for CSS and JavaScript under the static directory but you can change the names or move the CSS and Javascript files into different an assets folder.

(I am using GitHub and netlify. Changes can be made to the site’s theme and tested locally before saving to Github. )

As files in the public folder that are no longer needed are not deleted they need to be cleaned out. You can use rm -rf public to remove the existing public folder before building it again.

The hugo server --watch --verbose command monitors the content/ and theme directories for changes and rebuilds the site automatically.

The built-in web server supports live reload which means that as pages are saved on the server, the browser refreshes the page with the updated content.

find public -type f -name '*.html' | xargs ls -l

rm -rf public
hugo --verbose

Hugo uses the Go template engine which scans the template files for commands enclosed between {{ and }}. The logic in the template is run every time the site is built.

The range command is an iterator and is used to iterate through the HTML pages. This is used to dynamically generate output files. The .Title command prints the value of the title variable which comes from the front matter of the Markdown file. The end command means the end of the range iterator. Everything between range and end is evaluated.

This code here will list the first 10 posts from the content sections.

 {{ range first 10 .Site.Regular.Pages }}
    <h5>{{ .Title }}</h5>
  {{ end }}

This code will list the various content sections such as the blog/posts section, projects section, about section, contact etc as links.

 {{ range first 10 .Data.Pages }}
      <h5><a href="{{ .Permalink }}">{{ .Title }}</a></h5>
  {{ end }}

Note that some variable such as Data are created before any HTML output files. The content is loaded into the variable and the template processes this before creating the HTML files.

Posts are created in a section under the content/ directory. Some themes name the blog post section as “posts”, others use “post”. The type will be of the same type as the content section. (I also have a “projects” section which will have type “projects”). Hugo will use the section name to find the correct template file for each piece of content. If there is none it looks in the _default/ directory. So for blog posts it looks for the posts/single.html template, for projects posts it looks for the projects/single.html. Any content created that does not have a single.html template (such as the about or contact pages) will use the _default/single.html file.

find themes/my-theme -name single.html | xargs ls -l

<!-- _default/single.html -->
<head>
  <title>{{ .Title }}</title>
</head>
<body>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</body>

This code will go through the pages and checks if the type is “posts” (blog posts)or if the type is “page” for top-level pages that are not under a section such as the about page, contact page etc.

      <h2>List of blog posts</h2>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "posts"}}
      <h4><a href="{{ .Permalink }}">{{ .Title }}</a></h4>
    {{ end }}
  {{ end }}

  <h2>List of non-post pages</h2>
  {{ range .Data.Pages }}
    {{ if eq .Type "page" }}
      <h4><a href="{{ .Permalink }}">{{ .Title }}</a></h4>
    {{ end }}
  {{ end }}
    

Templates can be shared. Instead of rewriting the same code in different templates, you can use partial templates for common code. Partial templates can be used for the headers, footers, nav bar, head etc. Then the partial template is referenced within the other templates.

A path is no required for partial templates. {{- partial "nav.html" . -}}

{{- partial "header.html" . -}}

To list all the files under the theme:
find themes/new-theme-name -type f | xargs ls -l

To find all the index.html pages use the command:
find . -name index.html | xargs ls -l

To remove the public folder:
rm -rf public To rebuild:
hugo --verbose

The hugo server --watch --verbose command monitors the content/ and theme directories for changes and rebuilds the site automatically.

To see the html files built in the public folder:
find public -type f -name '*.html' | xargs ls -l

To clean up the piblic folder you can also run hugo --gc where GC is short for garbage collection.

• hugo --gc