Make Github Your Own CMS Using Hugo

Hello everyone. Last a few weeks I was thinking about making ozantopal.com great again. 😄 On that days, Hugo entered my life, thanks to Furkan’s advice. Hugo is a framework for building websites. It’s actually a static page generator. It’s written with Go and Hugo is quite fast.

After all those compliment to Hugo; I would like to return my main subject. Today, I wanna tell you about migration of my blog to Hugo and how I maintain new posts on that new ‘cms’.

Requirements

A GitHub account
Basic computer knowledge
A registered domain-name(optional)

Basic git knowledge is welcome but not mandatory.

Steps Of Creating Your Own Website

Installation Of Git

This has operating system dependent answer and that’s why I’m not going to explain how to install git but you can find the answer on this link. You need to follow the instructions for the operating system you are using.

Installation Of Hugo

This also has operating system dependent answer but I feel that I need to explain that part clearly.

On Linux&MacOS:
To install Hugo via brew, run this command on terminal
```
brew install hugo
```

On Windows: To install Hugo via chocolately, run this command on terminal

choco install hugo -confirm

P.S: In case of chocolately is not installed on your machine run the command below on powershell:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

After all that’s done, you can check whether hugo is installed or not via running command below on terminal:

hugo version

This should return something like Hugo Static Site Generator v0.79.1-EDB9248D windows/amd64 BuildDate: 2020-12-19T15:44:19Z

Generating New Site

Before I begin, I wanna remind you that I’m going to explain happy path here. In case of something went wrong, I strongly recommend you to refer Hugo’s Documentation.

First, we create a new site by running command

hugo new site {name-of-site}

Note: you should replace “{name-of-site}” with name of your site. I prefer here “my-sample-blog” as name.

That command gonna create a new folder with name of your site and generate number of different folders and files. We’ll pay attention on that files later but first you need to select a theme for your website. You can take a tour for Hugo themes for a while before but I’m going to explain Ananke Theme. First, download the theme from Github and add it to your site’s themes directory:

git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

After download is finished you need to define your theme on your config.toml file. For doing that run command below:

echo 'theme = "ananke"' >> config.toml

After that step you can serve your site by running command below but as you can realize you need to customize your site and for doing that you need to refer to theme’s documentation.

hugo server -D

Deployment Of Your Website On GitHub

When your customization is ready for production(i.e. you’re happy what you see when you check your site), then you need to create two repository on your github account. To do that use this url: http://github.com/new. One of your repository should named as “{your-github-username}.github.io” for hosting your page static page. Second repository can be named as you prefer.

Before pushing our codes to GitHub, create a “.github/workflows” folder on root of your site’s codes and then create a master.yml file under that folder. You can prefer anything else instead of master but file extension must be “.yml” and add codes right below:

name: CI
on: 
  push:
    branches:
      - master

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master
      - name: Update Theme
        # (Optional)If you have the theme added as submodule, you can pull it and use the most updated version
        run: git submodule update --init --recursive
      - name: Install Dependencies
        run: sh ./install.sh
      - name: Build
        run: hugo      
      - name: Archive Production Artifact
        uses: actions/upload-artifact@master
        with:
          name: public
          path: public

  deploy:
    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master
      - name: Download Artifact
        uses: actions/download-artifact@master
        with:
          name: public
          path: public
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.TOKEN }}
          external_repository: {your-github-username}/{your-github-username}.github.io
          publish_dir: ./public
          #   keep_files: true
          user_name: {Your Name}
          user_email: {Your Email}
          publish_branch: master
          cname: {yourdomain}

I want to explain what’s going on here but it’s about another concept named CI/CD and this blog post is not true place for doing that. Basically, we define here a pipeline for GitHub Actions to build our Hugo page and deploy it to GitHub’s free Pages. You just need to focus on line #43, #46, #47, #49 to replace information with your own. Note: Leave line #42 as same as it’s.

After that create a file with name install.sh and this name is mandatory because we use it on our pipeline’s file line #18. Then add commands I share below to this file:

# Install brew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install hugo
brew install hugo

Last but not least visit GitHub’s Personal Access Token Page and generate new token with whole repo scope selected.

Copy this token and generate new repository secret on https://github.com/{your-github-username}/{your-codebase}/settings/secrets/actions with name “TOKEN” on repository of your blog’s code. Name of this secret is a must cause of master.yml file’s line #42.

Then you finally need to push your code by running those git commands

git add .
git commit -m "{Commit MSG}"
git remote add origin https://github.com/{your-github-username}/{your-codebase-repo-name}.git
git push origin master

You need to customize text like “{…}” with your own and that’s it. Your page is active on http://{your-github-username}.github.io/ and if you have your domain name, then you just need to redirect your domain to IP address of Github Pages, aka 185.199.108.153.

Creating Content

I hope you enjoy and can create your own page. After all these are done. You can easily use your codebase repository to create your content under “/content/posts” folder as markdown(.md) file.

I hope this blog post was helpful for you. Keep blogging!

Ozan Topal