On the previous post, I have explained how to bootstrap the blog repository and its CICD and publish it to the public. The site is accessible from
https://<user>.gitlab.io/<repo-name>, in case of mine: https://bangau1.gitlab.io/my-blog/.
A bit of disclaimer, that is not my real blog repository. Mine is private :smile:
Hugo Directory and Content Structure
Disclaimer: I only explain the content structure of Hugo, the Hugo Template by Gitlab.
Now, before we take a look at some important configuration in Hugo, let me explain in general how the Hugo content structure
├── config.toml ├── content │ ├── _index.md │ ├── page │ │ └── about.md │ └── post │ ├── 2015-01-04-first-post.md │ ├── 2015-01-15-pirates.md ├── resources │ └── _gen │ ├── assets │ └── images ├── static │ └── favicon.ico └── themes └── beautifulhugo
This is the Hugo configuration file in
toml format that contains all settings about:
- information about the site: Author information and Social Link (e.g: Facebook, Twitter, GitHub, Gitlab, etc)
- the site system and content rendering parameter
You can use another Hugo supported format:
This is the content location. It consists of 2 subdirectories:
This is a placeholder where you can put all independent page that doesn't show like the post entry. For example:
Contact Us, and
All content in this folder will appear descendingly by post's published date. This will be your main folder where you put the site's posts.
It also has a special file
_index.md. This is for to display a sticky content Post entry. Let say you have a lot of posts and the reader will go through some pagination. This sticky content will be always displayed. It may be useful in some cases: such as Important Announcement to the readers.
TBH, I don't know much about this folder other than it is used by Hugo to generate the assets and images after doing some image processing. You can basically ignore this at this time.
In contrast to
resources folder, in
static directory you can put pretty much any static files in there. Normally you put Site's icon asset, the avatar, and other assets that you can think of.
Pretty obvious, it's to include the theme for the site. From Gitlab Hugo Template, by default, it uses
Hugo Important Configurations
Take a look at
config.toml file, this is the initial configuration generated by Gitlab Hugo template:
baseurl = "https://bangau1.gitlab.io/my-blog/" contentdir = "content" layoutdir = "layouts" publishdir = "public" title = "Beautiful Hugo" canonifyurls = true DefaultContentLanguage = "en" theme = "beautifulhugo" metaDataFormat = "yaml" pygmentsUseClasses = true pygmentCodeFences = true #disqusShortname = "XXX" #googleAnalytics = "XXX" [Params] subtitle = "Hugo Blog Template for GitLab Pages" logo = "img/avatar-icon.png" favicon = "img/favicon.ico" dateFormat = "January 2, 2006" commit = false rss = true comments = true # gcse = "012345678901234567890:abcdefghijk" # Get your code from google.com/cse. Make sure to go to "Look and Feel" and change Layout to "Full Width" and Theme to "Classic" #[[Params.bigimg]] # src = "img/triangle.jpg" # desc = "Triangle" #[[Params.bigimg]] # src = "img/sphere.jpg" # desc = "Sphere" #[[Params.bigimg]] # src = "img/hexagon.jpg" # desc = "Hexagon" [Author] name = "Some Person" email = "firstname.lastname@example.org" facebook = "username" googleplus = "+username" # or xxxxxxxxxxxxxxxxxxxxx gitlab = "username" github = "username" twitter = "username" reddit = "username" linkedin = "username" xing = "username" stackoverflow = "users/XXXXXXX/username" snapchat = "username" instagram = "username" youtube = "user/username" # or channel/channelname soundcloud = "username" spotify = "username" bandcamp = "username" itchio = "username" keybase = "username" [[menu.main]] name = "Blog" url = "" weight = 1 [[menu.main]] name = "About" url = "page/about/" weight = 3 [[menu.main]] identifier = "samples" name = "Samples" weight = 2 [[menu.main]] parent = "samples" name = "Big Image Sample" url = "post/2017-03-07-bigimg-sample" weight = 1 [[menu.main]] parent = "samples" name = "Math Sample" url = "post/2017-03-05-math-sample" weight = 2 [[menu.main]] parent = "samples" name = "Code Sample" url = "post/2016-03-08-code-sample" weight = 3 [[menu.main]] name = "Tags" url = "tags" weight = 3
I won't explain all of them, but only the important things to make your blog truly yours (not from template anymore)
This must be set correctly so Hugo can render the asset links correctly by using this
baseurl information. Please set it to the public domain and path of your site.
The title of your blog site.
This is commented by default. Please uncomment it so that you can use Disqus to provide reader able to comment on your blog post. Go to Disqus Homepage, sign up, retrieve the short name, and put it in
Hugo doesn't offer stats view analytics tool out of the box. However, you can use Google Analytics (GA) to gather knowledge about your blog stats view. Put your GA user id there, usually in the format
This is not displayed by default in the configuration file. But since emoji in our daily life has become a thing, I think using emoji in the blog would be nice added-value too. Just put
enableemoji = true in
[Param] section is for the subtitle of the blog.
These settings are important. Put the customized logo and favicon in the
static folder and refer it to the configuration.
For example, this is my blog configuration snippet
[Params] subtitle = "Movie lover. Engineer. DevOps" logo = "avatar.jpg" favicon = "avatar.jpg"
And I put the
avatar.jpg both for logo and favicon in
blog.agung.io/static ├── avatar.jpg
This is where you put all the information about the blog author and her/his social media link account. If you don't use some of them, you can just remove them from the configuration.
This is a special parameter to organize the top bar menu of the blog. Here you can specify multiple menus, name them, put it under the parent menu if you want, and sorted them by the
weight (low weight means the most left).
Example for this blog, I only have these 3 menus
[[menu.main]] name = "Blog" url = "" weight = 1 [[menu.main]] name = "About" url = "page/about/" weight = 2 [[menu.main]] name = "Tags" url = "tags" weight = 3
I think I've listed all necessary configuration to make the blog more personalized.
If you think there are other additional configurations that are important, please comment below :smile:
Test in Local
Now to play around with these configurations and contents without having to publish it first, you can test it locally first.
- Install Hugo binary that you can find the instruction here
- Go to the blog repository folder, then invoke
That command will build the blog and print information where you can access it locally. Normally it's
Pretty simple and fun right?
Next post, I am gonna tell you the workflow on creating a new blog post with Hugo. Stay tuned!