The Why, the What and the How

October 3, 2017    general guide

The Why

After many and many suggestions to start blogging, I finally decided to buy a domain, update my website and open a blog.

Of all the millions of good reasons, I primarly decided to open this platform to improve and organize my inner thoughts, improve my writing and explanation skills (especially in english) and finally to share my experiences, opinions and solutions to problems regarding both my field of study and my daily life.

Without going too much in depth, maybe I’ll clear my ideas in the process, I chose to dedicate my first post to something I wish I had read before starting this website, a concrete, concise and easy to follow how-to guide on how to open a blog and setup a custom domain.

The What

I had the idea of opening my own personal webpage almost one year ago but never managed to find time for diving into the big amount of options for platforms, domain registrars, website themes, and writing ideas.

Speaking about platforms, I was interested in some key aspects for the website: easiness in publishing blog posts, portability of articles, fast loading pages, github pages hosting and hopefully good looking themes. On one thing I was sure about: Wordpress was not an option. Probably it’s the most popular blogging platform for the less-techy ones but I prefer to write in a text editor (Sublime), and have a portable document that exists even without the platform. Also, all of the clutter in many wordpress themes not only makes the website super slow to load but distracts the reader in his reading experience.

I was searching for some tool that could have helped me both to introduce myself to the world and to blog easily at the same time and so using Facebook notes, Medium, Quora or other social based pages was not a good idea since I wanted people to visit it without having to register for some accounts.

The two main relevant counterparts I have considered were Jekyll and Hugo. I ended up choosing the second one mainly for the easiness in deploying the website and the well presented collection of presentation/blogging themes available. I eneded up using a slightly modified version of Sustain for the majority of the website together with Vitae for the resume page.

Regarding domain registrars it was an easy choice: goDaddy is so popular that, even though I never bought a domain, I trusted the environment and bought it without looking back. (Okay, the price also helped a lot in the choice.)

The How

Creating a website with Hugo

The installation guide for Hugo is very well done but in a few bullet points, to begin building a website with Hugo you just:

$ brew install hugo
$ cd myWebsiteFolder
$ hugo new

The last command will create a new website waiting to be populated and made public. A new theme can be installed in the themes folder and modifying the config.toml file you can control the specifics of your website.

During my first try, I was using the GitHub Pages free service to host my website. Basically, you host your website in a repo called yourGithubUsername.github.io and then everyone can access it from the same url.

Setting up a hugo website is straightforward, and to test it locally you can just use the hugo serve command. When you are happy with your website, the hugo command will build the website and create the static webpages inside the myWebsiteFolder/public folder. This is the folder that must synchronize with the master branch of your github repo.

Since I wanted both my full folder and my public folder synchronized in one single repository, I created two branches in my repo: the dev branch for the myWebsiteFolder folder, and the master branch for the myWebsiteFolder/public folder and to keep them always up to date I managed to create a script with the help of the hugo documentation to update the website instead of using the hugo command and keep both branches up to date (shown later below).

Setting up a personal domain

To port your website from GitHub pages to your all-new goDaddy domain, you just need to make a few changes to the repository and tweak some options in the domain settings. First of all, in the GitHub repo settings, in the custom domain field, insert your new domain.

Then, in the goDaddy settings go in the manage DNS page and input an A type record with value 192.30.252.153 and a CNAME type record with value yourGithubUsername.github.io as in the following picture.

Now you have to create a CNAME file (just name it like this) that must sit in the main folder of your website (and so inside the public folder of your main hugo folder). This is a one line file containing just the domain of your website so for me it looks like this:

rdednl.com

Since the public folder gets always deleted and built again after every hugo command, I created the CNAME file in my main folder and copy the file automatically with the script that I made.

Finally, my working directory, at least the relevant tree, looks like this:

├── CNAME
├── _scripts
│   └── publish.sh
├── archetypes
├── config.toml
├── content
│   ├── blog
│   │   └── the-why-the-what-and-the-how.md
│   └── projects.md
├── data
├── layouts
├── public
├── static
│   └── img
│       ├── profile.jpg
│       └── the-why-the-what-and-the-how
│           ├── github_pages_settings.png
│           └── godaddy_settings.png
└── themes
    └── hugo-sustain

where the publish.sh script is the one that I launch every time I have to commit my changes and looks as follows:

#!/bin/sh

DIR=$(dirname "$0")

cd $DIR/..

if [[ $(git status -s) ]]
then
echo "The working directory is dirty. Please commit any pending changes."
exit 1;
fi

echo "Deleting old publication"
rm -rf public
mkdir public
git worktree prune
rm -rf .git/worktrees/public/

echo "Checking out master branch into public"
git worktree add -B master public origin/master

echo "Removing existing files"
rm -rf public/*

echo "Generating site"
hugo

echo "Copying CNAME"
cp CNAME public/

echo "Updating master branch"
cd public && git add --all && git commit -m "Publishing to master (publish.sh)"

echo "Publishing to remote repo"
git push origin master

Making a new blog post

One of the reasons I chose Hugo was the easiness of creating and publishing a new blog post. To create one, just go inside the content/blog directory and create a new markdown document.

$ cd content/blog
$ vi the-why-the-what-and-the-how.md

The document should always start as follows:

---
layout: post
title:  "The Why, the What and the How"
date:   2017-09-25 10:00:00
---

The content goes here.

Congratulations, you have just made your first blog post!

Well, I actually think that the main purpose of this article was learning the Markdown syntax, as if online cheat sheets were not enough, and don’t leave my blog page completely empty. I think I got the job done, till I have something more personal and interesting to write.



comments powered by Disqus