My thoughts

I always wanted to setup a blog and keep updating the best practice which I learned from work(in eBay) and self study. It may be helpful by other peoples who met issue and clicked into this page. I would be very proud of this.

We used to search on the internet when we are facing issues. We keep digging and digging, trying again and again to resolve problems. A common case is many blogs are just pasted from anothor, that is very time wasting once we realised. So I will always write original blogs, and don’t forget the initial purpose.

Now let me begin recording my struggling blog build road. I had to say the quick_start part in hugo document is not friendly… The blank site on localhost:1313 drives me crazy..

install brew

brew

/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

Install hugo

hugo

brew install hugo

Create site and add your favorate theme

create main folder by hugo new command.

hugo new site your_site_name

cd your_site_name, then clone your favorate hugo them into themes/.

cd your_site_name
git clone https://github.com/Track3/hermit.git themes/hermit

create some web pages in .md format, following commands will automatically generate subfolder names posts and about.

hugo new posts/my-first-post.md
hugo new about/about.md

Ather this, hugo ducument says hugo server -D But I saw nothing when opened http://localhost:1313/. After a huge struggling, I finally saw the contents.

Needed actions are:

  1. Remove draft line in *.md you just created, hugo won’t deploy drafts unless you append this command --buildDrafts. However, after I made change accordingly, website still is blank.
  2. Copy config.toml from your themes/theme_name/exampleSitefolder to your site main folder. And modify some customer settings, I am only listing necessary parts:
baseURL = "https://Thunsis.github.io"
# your github.io url
theme = "hermit"
# them name
[menu]

  [[menu.main]]
    name = "Posts"
    url = "posts/"
    weight = 10

  [[menu.main]]
    name = "About"
    url = "about/"
    weight = 20
# menu stucture, need to be aligned with /content/ subfolders you created

Now you can see the website by, congratulations!

hugo server -D

Deploy to github repo

We have get blog ready in localhost, but there still a way to go.. Carry on!

Create your_name.github.io repo and configure it

I won’t go into details on creating repo names your_name.github.io, there is an important action need, which is to create a file names .github/workflows/gh-pages.yml under your just created repo. The content should be:

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Generate static files and push to repo

After this command, static files will be generated to hugo project subfolder names public. Which is the exact content we need to deploy to github repo.

hugo

Now we push it to repo.

cd public 
git init
git add .
git commit -m "my blog"
git branch -M main
git remote add origin https://<your_token>@github.com/Thunsis/Thunsis.github.io
git push -u origin main
git branch --set-upstream-to=origin/main

When you need to re-config local repo when blog contect already exists in github, need to run below commands.

mkdir public
cd public
git init
git remote add origin https://<your_token>@github.com/Thunsis/Thunsis.github.io
git fetch --all
git checkout -f main
git reset --hard origin/main
touch test1.md
cd public
git add .    
git commit -a -m 'my blog'
git push -u origin main

See you blog on http://your_name.github.io/, cheers!

Conclusion

The mosting blocking issues:

  • hugo document did not tell us to overwrite config.toml by theme’s, which caused I can’t see the content.
  • Muti github account issue(personal issue). But I have found best solution, will post another blog to summary that. I think it could be helpful by some people, because most of us have company github account and personal github account both on same laptop.

P.S.1 Sync .md files to github

create a repo names blog, then execute below commands as below:

cd content
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://<your_token>@github.com/Thunsis/blog
git branch --set-upstream-to=origin/main 
git push

P.S.2 Change to use yinyang theme

Clone theme(in your site root path).

git clone https://<your_token>@github.com/joway/hugo-theme-yinyang themes/yinyang

Edit config.toml. for example:

baseURL = "https://func.fun/"
languageCode = "en-us"
title = "Xuan"
theme = "yinyang"
DefaultContentLanguage = "cn"
enableRobotsTXT = true
canonifyURLs = false

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
    guessSyntax = true
    noClasses = true
    style = "tango"
    tabWidth = 2

[author]
  name = "Xuan"
  homepage = "https://func.fun/"

[params]
headTitle = "Xuan"
description = "Data is the air that a company breathes."
lazyImage = true

[[params.socials]]
name = "About Me"
link = "https://func.fun/about"
[[params.socials]]
name = "Github"
link = "https://github.com/thunsis"

Also you can refer to developer config.