Starting a Hugo website

Series - sticky-post

https://gohugo.io/getting-started/installing

/first-post/images/hugo1.png

Add Hugo to your Windows PATH settings:

/first-post/images/hugo2.png

At the prompt, type hugo help and press the Enter key. You should see output that starts with:

/first-post/images/hugo3.png

If you do, then the installation is complete.

1
2
cd C:\Hugo\Sites
hugo new site my_blog

You should now have a directory at \Sites\my_blog

/first-post/images/hugo4.png

https://hugodoit.pages.dev/theme-documentation-basics

Download the latest release and extract it in the themes directory. Or,

clone this repository to the themes directory:

1
git clone https://github.com/HEIGE-PCloud/DoIt.git themes/DoIt

or using Github Desktop:

/first-post/images/hugo5.png

The following is a basic configuration for the DoIt theme, by modifying config.toml in \Sites\my_blog

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
baseURL = "http://example.org/"
# [en, zh-cn, fr, ...] determines default content language
defaultContentLanguage = "en"
# language code
languageCode = "en"
title = "My New Hugo Site"

# Change the default theme to be use when building the site with Hugo
theme = "DoIt"

[params]
  # DoIt theme version
  version = "0.2.X"

[menu]
  [[menu.main]]
    identifier = "posts"
    # you can add extra information before the name (HTML format is supported), such as icons
    pre = ""
    # you can add extra information after the name (HTML format is supported), such as icons
    post = ""
    name = "Posts"
    url = "/posts/"
    # title will be shown when you hover on this menu link
    title = ""
    weight = 1
  [[menu.main]]
    identifier = "tags"
    pre = ""
    post = ""
    name = "Tags"
    url = "/tags/"
    title = ""
    weight = 2
  [[menu.main]]
    identifier = "categories"
    pre = ""
    post = ""
    name = "Categories"
    url = "/categories/"
    title = ""
    weight = 3

# Markup related configuration in Hugo
[markup]
  # Syntax Highlighting (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false is a necessary configuration (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

Create Your First Post

1
2
cd C:\Hugo\Sites\my_blog
hugo new posts/first_post.md

By default all posts and pages are created as a draft. If you want to render these pages, remove the property draft: true from the metadata, set the property draft: false or add -D or --buildDrafts parameter to hugo command.

1
 hugo serve

It is highly recommended that you add --disableFastRender parameter to hugo server command for the live preview of the page you are editing.

1
hugo serve --disableFastRender

A few suggestions to help you get a good looking site quickly:

  • Keep post pages in the content/posts directory, for example: content/posts/my-first-post.md

  • Keep other pages in the content directory, for example: content/about.md

  • Local resources organization

Note

There are three ways to reference local resources such as images and music:

  1. Using page resources in page bundles. You can reference page resources by the value for Resources.GetMatch or the filepath of the resource relative to the page directory directly.
  2. Store resources in the assets directory, which is /assets by default. The filepath of the resource to reference in the post is relative to the assets directory.
  3. Store resources in the static directory, which is /static by default. The filepath of the resource to reference in the post is relative to the static directory. The priority of references is also in the above order.

There are many places in the theme where the above local resource references can be used, such as links, images, image shortcode, music shortcode and some params in the front matter.

  • title: the title for the content.

  • subtitle: DoIt NEW | 0.2.0 the subtitle for the content.

  • date: the datetime assigned to this page, which is usually fetched from the date field in front matter, but this behaviour is configurabl in the site configuration.

  • lastmod: the datetime at which the content was last modified.

  • draft: if true, the content will not be rendered unless the --buildDrafts/-D flag is passed to the hugo command.

  • authors: DoIt CHANGED | 0.2.12 the list of authors for the content.

  • description: the description for the content.

  • license: the special lisence for this content.

  • images: page images for Open Graph and Twitter Cards.

  • tags: the tags for the content.

  • categories: the categories for the content.

  • series: DoIt NEW | 0.2.12 the series for the content.

  • series_weight: DoIt NEW | 0.2.13 define the position of the post in the series.

  • seriesNavigation: DoIt NEW | 0.2.13 whether to enable series navigation.

  • featuredImage: the featured image for the content.

  • featuredImagePreview: the featured image for the content preview in the home page.

  • hiddenFromHomePage: if true, the content will not be shown in the home page.

  • hiddenFromSearch: DoIt NEW | 0.2.0 if true, the content will not be shown in the search results.

  • twemoji: DoIt NEW | 0.2.0 if true, the content will enable the twemoji.

  • lightgallery: if true, images in the content will be shown as the gallery.

  • ruby: DoIt NEW | 0.2.0 if true, the content will enable the ruby extended syntax.

  • fraction: DoIt NEW | 0.2.0 if true, the content will enable the fraction extended syntax.

  • fontawesome: DoIt NEW | 0.2.0 if true, the content will enable the Font Awesome extended syntax.

  • linkToMarkdown: if true, the footer of the content will be shown the link to the original Markdown file.

  • linkToSource: DoIt NEW | 0.2.14 if false, turn off the view source link in the footer. You can set it to the link to the source file of the post. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.

  • linkToEdit: DoIt NEW | 0.2.13 if false, turn off the edit this page link in the footer. You can set it to the link to edit the page. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.

  • linkToReport: DoIt NEW | 0.2.14 if false, turn off the report issue link in the footer. You can set it to the link to report issues about the page. Use the magic variables: {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md, {title} to specify the title of the post, for example, the {title} for this post is Theme Documentation - Content and {url} to specify the url of the post, for example, the {url} for this post is https://hugodoit.pages.dev/theme-documentation-content/.

  • rssFullText: DoIt NEW | 0.2.4 if true, the full text content will be shown in RSS.

  • pageStyle: DoIt NEW | 0.2.11 adjust the page layout style, “normal” or “wide”.

  • license: DoIt NEW | 0.2.14 set the license info (HTML format is supported).

  • toc: DoIt CHANGED | 0.2.9 the same as the params.page.toc.

  • code: DoIt NEW | 0.2.0 the same as the params.page.code.

  • table: DoIt NEW | 0.2.14 the same as the params.page.table.

  • math: DoIt CHANGED | 0.2.0 the same as the params.page.math.

  • mapbox: DoIt NEW | 0.2.0 the same as the params.page.mapbox.

  • share: the same as the params.page.share.

  • comment: DoIt CHANGED | 0.2.0 the same as the params.page.comment.

  • library: DoIt NEW | 0.2.7 the same as the params.page.library.

  • seo: DoIt NEW | 0.2.10 the same as the params.page.seo.

  • outdatedArticleReminder: DoIt NEW | 0.2.13 the same as the params.page.outdatedArticleReminder.

  • sponsor: DoIt NEW | 0.2.13 the same as the `params.sponsor.


Info
  • I’m still learning Hugo and its features in order to get the most out of it, so for now, you can check out these resources to fully understand how to build a Hugo website.

  • This tutorial has covered the majority of how to use the DoIt theme, which is used on my website. You might also want to look at  these tests for more detailed examples on various cases.

  • I’ll update this article once I’m confident enough to deliver its content, so that I can share my experience working with Hugo.