Building this website using open-source tools and hosting it for free

For a while, I have been considering building a website to document things I learn. This year I decided to stop procsanating and get started with it.

Introducing patelhiren.com in all its glory. 🎉

Goals

For this site I had a few basic goals in mind.

• It should serve as a log to help me remember and reivew how I did things. I hope that others may find it helpful as well.
• The website should be fast and light. Should not be overburdened with Javascript.
• Should be able to host website with a simple webserver. No server side software should be necessary.
• Allowed me to keep my content in a standard text + image format for easy parsing even when not viewing via a browser. I did not want my content to be stored in binary formats in a database. I want it to be stored in plain text files on the filesystem.
• Support code syntax highlighting.
• Support SSL encryption on the website.
• Support emoji.

The above goals meant I was going to be building a Static Site using one of the many Static Site Generator Tools

Tools

After deciding I wanted a static site, I researched the various Static Site Generator Tools and settled on Hugo as my choice.

Hugo written in Go, is highly reviewed and praised for its speed of site generation. It supports macOS (my primary OS of choice), Windows, Linux, OpenBSD and FreeBSD. It has a very well documented site and looks to have an active community developing and supporting it. It allows me to create my content in Markdown syntax thus allowing me to keep it in plain text on the filesystem. It also supports code syntax highlighting and emoji 👌. You can check details of Hugo’s Makrdown support at markdownguide.org

Hugo supports a variety of Themes. I settled on Notepadium because it provided most of what I wanted out of box. I plan to customize it a bit to my liking as I learn more.

Hosting

For hosting I decided to use GitHub Pages. GitHub Pages is free, supports SSL and provides automatic CDN for serving fast webpages closer to your user. It also had the added benefit of having my generated site auotmatically have commit history and remote backup.

Installing Hugo and Building your site

I use macOS as my primary OS so these steps are for for the Mac. However the steps should be very similar if you are using any other supported OS. Homebrew and git ¹ is expected to be installed before you follow the rest of the steps.

Install Hugo

1

brew install hugo

To verify the install run

1

hugo version

Create your new site

1

hugo new site patelhiren.com

Add the Notepadium Theme

1
2
3

cd patelhiren.com
git init
git submodule add https://github.com/cntrump/hugo-notepadium themes/notepadium

Activate the theme for your site by adding it to the config.toml

1

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

Create a new post ²

1

hugo new blog/my-first-post/index.md

You can find your content under content folder. You can open the newly created index.md file in any Markdown editor of choice ³ and edit and save your content. Here is an example post to suggest what’s possible.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
title: "My First Post"
description: "This is my first post in Hugo. This shows up in Google search."
date: 2020-04-18T16:08:20-04:00
draft: true
tags: [
    "Tag 1",
    "Tag 2"
]
categories: [
    "Category 1",
    "Category 2"
]
---

Hello everyone welcome to you website.

<!--more-->

This is the extended content of my first post.

Once you save your content you can test it locally by activating Hugo local web server.

1

hugo server -D

You can navigate to your local site at http://localhost:1313/.

Edit you config.toml to configure the rest of your site settings. Here is mine.

 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

baseURL = "https://patelhiren.com/"
languageCode = "en-us"
title = "Hiren Patel"
theme = "notepadium"
copyright = "©2020 Hiren Patel."
enableEmoji = true
enableRobotsTXT = true

[markup.highlight]
codeFences = true
noClasses = false
linenos = true

[markup.goldmark.renderer]
unsafe = true  # enable raw HTML in Markdown

[params]
style = "auto"  # default: auto. light: light theme, dark: dark theme, auto: based on system.
dateFormat = "Jan 02, 2006"  # if unset, default is "2006-01-02"
readingTime = false  # show reading time after article date
logo = "patelhiren-logo.png"
slogan = "Documenting things as I learn."

[params.assets]
css = ["css/fonts.css", "css/light.css", "css/dark.css"]

[params.comments]
enable = false  # En/Disable comments globally, default: false. You can always enable comments on per page.

[params.share]
enable = false  # En/Disable share globally, default: false. You can always enable share on per page.
addThisId = ""
inlineToolId = ""

[params.math]
enable = false # load math globally, default: false. You can always enable math on per page.
use = "katex"  # builtin: "katex", "mathjax".  default: "katex"

[params.syntax]
use = "none"  # builtin: "prismjs", "hljs". "none" means Chroma
theme = "xcode"
darkTheme = "xcode-dark"

[params.nav]
showCategories = true       # /categories/
showTags = true             # /tags/

To build your static site run:

1

hugo -D

The output will be saved under ./public/ directory. You may copy the contents of this folder to any webserver and your website will be servered.

Hosting your site on GitHub Pages

• Create a repository to hold your Hugo content and source files on GitHub. Mine is called patelhiren.com
• Create a repository called <username>.github.io. Replace <username> with your GitHub username. Mine is called patelhiren.github.io.
• Clone your source project via:

1
2

# adjust to match your git url.
git clone [email protected]:patelhiren/patelhiren.com.git

• Paste your existing source files in the new repository folder.

• Run and verify your local Hugo files from local repo by running hugo server -D and accessing the site at http://localhost:1313/.

• Once you are happy with the results:

  • Press Ctrl+C to kill the server
  • Before proceeding completely remove the public directory

• Add your public site as a git submodule. Like so:

1
2

# adjust to match your GitHub Pages repo
git submodule add -b master [email protected]:patelhiren/patelhiren.github.io.git

Automating the deployment process

Create a new file deploy.sh and set its contents to below script. This will allow you to run deploy.sh to build your site and deploy to GitHub in one go.

 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

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Go To Public folder
cd public

# Discard local changes on public folder
git reset
git checkout .
git clean -fdx

# Pull the latest changes before updating
git checkout master
git pull origin master

cd ..

# Garbage collect hugo image-processing generated images.
hugo --gc

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
  msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

• Your site will then be available at https://<username>.github.io.

Customizing GitHub pages to use a custom domain

If you plan to use your own doamin instead of the <username>.github.io you need to follow the guide at Managing a custom domain for your GitHub Pages site.

For my site I did the following:

• Create a file called CNAME and set its contents to patelhiren.com.
• Added the CNAME file to the git repo at patelhiren.github.io.
• Got to Repo Settings at https://github.com/patelhiren/patelhiren.github.io/settings and set Custom domain and Enforce HTTPS settings.

GitHub Pages Custom Subdomain Settings

Publishing new Post/Changes

To publish a new post:

• Create a new post similar to to command below.

1

hugo new blog/my-new-post/index.md

• Set and edit your post using Markdown tools.

• Run and verify your local Hugo files from local repo by running hugo server -D and accessing the site at http://localhost:1313/.

• Run deploy.sh to deploy your site.

• Commit your changes to your source repo.

Conclusion

This is all that should be necessary. It looks like a lot of steps, but in practice it is very simple and doesn’t require as much work to maintain for publishing new posts.