Background

The goal of this blog is to make written content production as streamlined and minimal as possible. I write everything in Markdown using Bear/Editorial and VSCode. I push updates using Git to a private repository in GitHub, which is integrated with Netlify to automate CI/CD (and to use their CDN).

If you don’t know what any of that means, don’t sweat it. I’m working on technical documentation to make these design decisions and instructions as clear as possible.

Until then, the following guide is what I believe to be the simplest way to blog on a custom domain at present. Instead of spending a ton of time pointing and clicking, inevitably getting distracted, and losing your train of thought (and therefore productivity), you are able to strip everything down to the most essential elements.

Step 1: Create your accounts

You’ll need GitHub and Netlify

Step 1: Create Github account (if you don’t already have one)

  • Go to the Github website and create an account
  • Create a new Github repo
  • Choose to initialize it with a README.md
  • Keep your repository page in one tab, open a new one

Step 2: Create a Netlify account

  • Go to the Netlify website
  • Create an account using your GitHub account
  • Create a site using the repo you just created in GitHub
  • Add the build command hugo and the path /public

Great! That’s it for now.

Step 2: Clone your GitHub repo onto your local machine

This allows you to simply push your changes to the web using the command line

Step 2.1: Open Your Terminal

Mac: Command + spacebar -> type “terminal” -> Enter Windows: Win + R -> “cmd”

You should see a new application running. This is called the CLI – it allows you to give declarative commands to the machine.

Step 2.2: Install a Package Manager

In order to install programs like git via CLI, you need something called a package manager, which basically handles all of standard point-and-click installation tasks depending on the application. There are a lot of different package managers available, but the most popular ones are homebrew (for MacOS) and chocolatey (for Windows)

Mac: Follow the instructions on the Homebrew website. (They’re very simple & straightforward.) Windows: Follow the instructions on the Chocolatey website.

Step 2.3: Install Git

Next, you’ll need to install Git. To check if you have git installed, try the following command:

git --version #checks the version of git

If you get an error, then install git:

Mac

brew install git #installs git

Windows

choco install git #installs git

Step 1.3: Clone your website’s Github repo

  • Use the terminal to navigate to a folder in which you’d like to store your files
  • Try to avoid folders that are shared or have auto-cloud backup enabled (like Dropbox or iCloud), because these can make things more complex.
  • Use your web browser to navigate to the Github repo for your site
  • Click on the green button that says Code, and then
cd your/project/directory #change into the local directory where you want to host your site
git clone <find the > #initialize your git repository

You should see some logs in the terminal confirming that the repo has been initiated. If you get an error, you can try the following command to ensure git is installed:

git --version

Step 2: Install Hugo

Go to the Hugo Site and follow the instructions. You’ll need to have Go insalled!

brew install hugo #installs hugo
hugo version #checks the versision for your reference
hugo new site <yoursitename> #creates your site (use your name and exclude <> signs)

Step 2.1: Add a Theme

  • Next, we need to add a theme. For this guide, we’ll use the theme I’m using, Tokiwa.
  • Feel feee to pick out any theme from the Hugo themes list, though.
    • All you’ll need to do is simply find the theme’s github URL, which should end in .git like below.
git submodule add https://github.com/heyeshuang/hugo-theme-tokiwa.git themes/hugo-theme-tokiwa

Step 2.2: Add the Theme to Your Site’s Configuration

  • You can use the command echo to change something inside of a file.
  • You can use the operarant >> to write a line of code or text to a file.
  • Your site has a file called config.toml which specifies things like theme, name, description, etc.
  • The following command uses echo and >> to change the “theme” property in config.toml to the theme you want to use (in our case, hugo-theme-tokiwa).
echo 'theme = "hugo-theme-tokiwa"' >> config.toml

Step 3: Add some Content

  • You can use the command hugo to create new pages.
  • The first command below uses hugo to create a new page called about.md with the text Hello world!
  • The second command uses hugo to create a new blog post called my-first-blog-post.md
hugo new about.md >> Hello world!
hugo new posts/my-first-blog-post.md

Step 4: Start Your Local Server

  • In order to view your Hugo site, it needs to be running on a server (in this case, your local machine)
  • The command below uses Hugo to start a server.
hugo server -D

Now you should be able to view your site on localhost://1313

Step 6: Commit Your Changes

git add .
git commit -m "Commit message"
git push

Step 7: Upload Your Repo with Github

  • Go to Github
  • Create an account (if you don’t have one already)
  • Go to Repos -> Create New Repo
  • Enter your information and do not check the “Add README.md” box
  • Copy the script for “…or push an existing repository from the command line” (below)

Should be something like this:

git remote add origin [email protected]:haydenlewis/your-hugo-site.git
git push -u origin master
  • Past this script into your project’s root directory and then hit Enter. You should see that your project has been added to your repos.

Step 7: Integrate Netlify

  • Go to the Netlify website

  • Create a Netlify account

  • Go to Sites -> New Site From Git

  • Choose the repo that you want to use

  • Link your Github repo

Step 8: Push Live Changes!

Just update anything inside of VSCode and push using Git!

I really dig this because it allows me to use Floam directly alongside my work.

I have another post on Floam in the works, too. Stay tuned!