Complete Website Setup Guide by GitHub and Hugo

May 19, 2021 · 5 min read · Hugo Clarity GitHub Tutorial  ·
Share on:
Complete Website Setup Guide by GitHub and Hugo

Overview

I've been blogging in many different places like blogspot, Medium and even Linkedin. I'm tired with bad editors and feel quite comfortable with simply markdown.

While I realize that Hugo can do a good job building website and the potential to host it purly on GitHub, that makes a lot of sense to me as I can draft and share posts, tutorials, tips like maintaining code in my repo.

So let's get started.

And, since the website is powered by Hugo and is hosted on GitHub, let me start with a blog sharing what I did setting it up in details.

Note: I did all these on my MacBook Pro. So your mileage may vary.

Updates (after initial post):

  1. Aug 2013: Updated to fix Hugo issue by adding extended: true in "Setup Hugo" step: `Error: error building site: TOCSS: failed to transform "sass/main.sass" (text/x-sass). Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.
  2. Aug 2013: Updated to detail out the Github token process.

Step 1: Install Hugo

Prerequisites:

  • Git is installed
  • brew is installed
1# Install hugo
2$ brew install hugo
3
4# Check
5$ hugo version
6hugo v0.83.1+extended darwin/amd64 BuildDate=unknown

Step 2: Create a New Site

 1$ hugo new site brightzheng100
 2Congratulations! Your new Hugo site is created in /Users/brightzheng/development/blog/brightzheng100.
 3
 4Just a few more steps and you are ready to go:
 5
 61. Download a theme into the same-named folder.
 7   Choose a theme from https://themes.gohugo.io/ or
 8   create your own with the "hugo new theme <THEMENAME>" command.
 92. Perhaps you want to add some content. You can add single files
10   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
113. Start the built-in live server via "hugo server".
12
13Visit https://gohugo.io/ for quickstart guide and full documentation.
14
15$ cd brightzheng100
16$ git init
17Initialized empty Git repository in /Users/brightzheng/development/blog/brightzheng100/.git/

Step 3: Add a Theme

Pick your prefered theme from here: https://themes.gohugo.io/. This is the one I picked: https://themes.gohugo.io/hugo-clarity/

 1# Clone it as a sub module
 2$ git submodule add https://github.com/chipzoller/hugo-clarity themes/clarity
 3Cloning into '/Users/brightzheng/development/blog/brightzheng100/themes/clarity'...
 4remote: Enumerating objects: 3126, done.
 5remote: Counting objects: 100% (285/285), done.
 6remote: Compressing objects: 100% (125/125), done.
 7remote: Total 3126 (delta 150), reused 249 (delta 136), pack-reused 2841
 8Receiving objects: 100% (3126/3126), 5.15 MiB | 8.37 MiB/s, done.
 9Resolving deltas: 100% (1809/1809), done.
10
11# Copy or move over the sample site
12$ ls
13archetypes  config.toml  content  data  layouts  static  themes
14$ ls themes/clarity/exampleSite/
15archetypes  config  content  layouts  LICENSE  README.md  resources  stati
16$ cp -a themes/clarity/exampleSite/* .
17$ ls
18archetypes  config  config.toml  content  data  layouts  LICENSE  README.md  resources  static  themes
19
20# Enable the theme
21$ echo theme = \"clarity\" >> config.toml

Step 4: Add Some Content

You can manually create content files (for example as content//.) and provide metadata in them, however you can use the new command to do a few things for you (like add title and date):

1$ hugo new post/getting-started.md
2/Users/brightzheng/development/blog/brightzheng100/content/post/getting-started.md created

Step 5: Start the Hugo server

Now, start the Hugo server with drafts enabled:

1$ hugo server -D

Step 6: Customize the Theme

Your new site already looks great, but you will want to tweak it a little before you release it to the public.

Open up config.toml in a text editor:

1baseURL = "https://example.org/"
2languageCode = "en-us"
3title = "My New Hugo Site"
4theme = "ananke"

Step 7: Build static pages

It is simple. Just call:

1hugo -D

Note: Output will be in ./public/ directory by default (-d/--destination flag to change it, or set publishdir in the config file).

Step 8: Further Customization

Language

1/config/languages.toml

What I've done:

  • Updated the supported languages with English only for now
1/config/_default/menu.en.toml

What I've done:

  • Refined the menu items

Params

1/config/_default/params.toml

What I've done:

  • Changed the params by following the comments
  • Major changes including introDescription, mainSections, logo, footerLogo, iconsDir etc.

archetypes

1/archetypes

What I've done:

  • added diary.md
  • and updated all these "templates"

Favicon

Built a favicon with 32x32 specs. Created a new folder named icons under /static and put the favicon as favicon-32x32.png under this folder.

Step 9: Host It on GitHub

  1. Create two repositories:
  • <USERNAME>/<USERNAME>.github.io.private to host Hugo project we built above, as a private project, like brightzheng100/brightzheng100.github.io.private -- well, the naming here is not important;
  • <USERNAME>/<USERNAME>.github.io.private to host the published website, as a public project, like brightzheng100/brightzheng100.github.io -- the naming is important as per GitHub's convention.
  1. Generate a new personal access token in: https://github.com/settings/tokens.

When using "Fine-grained personal access tokens", which is recommended, make sure to:

  • Select "Only select repositories", with the public repo, in my case it's "brightzheng100/brightzheng100.github.io"
  • In Permissions section, select "Repository permissions", with "Contents" as "Read and write" and "Metadata" as "Read-only"

And then make a copy of the token generated.

  1. Create a Secret named TOKEN under <USERNAME>/<USERNAME>.github.io.private.

  2. Add .github/workflows/gh-pages.yml to enable GitHub Actions:

 1mkdir -p .github/workflows
 2
 3cat > .github/workflows/gh-pages.yml <<'EOF'
 4name: Hugo Website Generator
 5
 6on:
 7  push:
 8    branches:
 9      - main    # Note: I'm using main branch in my private repo
10
11  # Allows you to run this workflow manually from the Actions tab
12  workflow_dispatch:
13
14jobs:
15  deploy:
16    runs-on: ubuntu-20.04
17    steps:
18      - uses: actions/checkout@v2
19        with:
20          submodules: true  # Fetch Hugo themes (true OR recursive)
21          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
22
23      - name: Setup Hugo
24        uses: peaceiris/actions-hugo@v2
25        with:
26          hugo-version: 'latest'
27          extended: true
28
29      - name: Build
30        run: hugo --minify
31
32      - name: Deploy
33        uses: peaceiris/actions-gh-pages@v3
34        if: github.ref == 'refs/heads/main'
35        with:
36          personal_token: ${{ secrets.TOKEN }}
37          external_repository: brightzheng100/brightzheng100.github.io
38          publish_branch: master
39          publish_dir: ./public
40EOF
  1. Commit and push our code to the private project:
1git add .
2git commit -am "initial commit"
3git branch -M main
4git remote add origin git@github.com:brightzheng100/brightzheng100.github.io.private.git
5git push -u origin main

Daily Blog / Diary Updates

In day 2 and beyond, if you want to add new blogs / diaries, simply do this:

  1. Add a new markdown file in corresponding folder, say blogs in /content/post or diaries in /content/diary;
  2. Add new images in /static/images/<YYYY> folder and refer them in your blogs / diaries.

That's it!

References