Featured image of post Hugo Blog Setup
Guide

Hugo Blog Setup

How to setup Hugo site with Cloudflare and Github

This guide will cover the following:

  1. Install Hugo
  2. Create a site using Hugo
  3. Install Hugo theme
  4. Push site to Github
  5. Host the site using Cloudflare

Install Hugo

Hugo is a static site generator written in Go. To install Hugo we have to make sure we have the following installed:

  1. Git
  2. Go
  3. Dart Sass

✅ You can follow the official installation guide and pick your operating system for the most up-to-date instructions. Below are some common examples.

Mac (install using brew): brew install hugo

💡 Homebrew is a package manager for MacOS, you can install by running the following install script if you don’t have it already.

1

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

After installing Homebrew, you can use the brew install hugo command above.

On Debian/Ubuntu:

1
2

sudo apt update
sudo apt install hugo

On Windows (using Chocolatey):

1

choco install hugo -confirm

💡 Chocolatey is a package manager for Windows. You can install it by following the instructions on their website if you don’t have it.

Hugo Quick start

After installing Hugo and Git we can start creating a site in the command line.

1. We first check to see if Hugo is installed and its version

Open your terminal or command prompt and run:

1

hugo version

This should output the Hugo version you have installed. If you get an error, double-check your Hugo installation.

2. Initialize Hugo project

Run the following command in your terminal (replace blog_name with your preferred project name, e.g., my-awesome-blog):

Reference: Official Hugo Quick start

1
2

hugo new site blog_name
cd blog_name

hugo new site blog_name will create a new folder called blog_name and initialize the basic template for a Hugo site.

cd blog_name changes your current directory into the newly created blog_name folder. All subsequent commands in the tutorial will be run from within this directory unless otherwise specified.

3. Start the Hugo server (optional for now, but good to test)

To quickly see a bare-bones version of your site, you can start the Hugo development server:

1

hugo server -D

💡 -D flag includes drafts. We’ll talk about drafts later when creating content.

This command starts a local development server. By default, it will be available at http://localhost:1313/. Open this address in your web browser to see your new Hugo site. It will be very basic at this stage without a theme. Press Ctrl+C in your terminal to stop the server.

Install Hugo Theme

Hugo themes determine the look and feel of your website. There are many free and open-source themes available.

  1. Browse Hugo Themes: Go to https://themes.gohugo.io/ and explore the available themes. Find one that you like. For this tutorial, let’s use the popular theme Ananke.

  2. Add Theme as a Git Submodule: The recommended way to install themes is using Git submodules. In your blog_name directory, run the following command, replacing your-chosen-theme-git-repo-url with the Git repository URL of your chosen theme. For Ananke, use the following:

    1
2

    git init  # Initialize git if you haven't already (should be done by hugo new site)
git submodule add [https://github.com/theNewDynamic/gohugo-theme-ananke.git](https://www.google.com/search?q=https://github.com/theNewDynamic/gohugo-theme-ananke.git) themes/ananke
    • git init initializes a Git repository in your project folder if it’s not already initialized. hugo new site should already do this, but it’s good to ensure.
    • git submodule add ... themes/ananke adds the Ananke theme repository as a submodule to your themes/ananke directory. This keeps your theme separate and makes updating easier.

  3. Configure Hugo to use the theme: Open the hugo.toml file in the root of your blog_name directory. Add the following line to tell Hugo to use the Ananke theme:

    1

    theme = "ananke"

    If you chose a different theme, replace "ananke" with the name of your theme directory (usually the theme name).

  4. Test the theme locally: Start the Hugo server again to see your site with the new theme applied:

    1

    hugo server -D

    Refresh your browser at http://localhost:1313/. You should now see your site styled by the Ananke theme (or your chosen theme).

Create your first post

Let’s create a sample blog post.

  1. Create a new content file: Use the hugo new command to create a new markdown file for your post. For example, to create a post named “my-first-post.md” in the posts section:

    1

    hugo new posts/my-first-post.md

    This command creates a file at content/posts/my-first-post.md.

  2. Open and edit the content file: Open content/posts/my-first-post.md in your favorite text editor. You’ll see some front matter at the top, enclosed in --- delimiters:

    1
2
3
4
5

    ---
title: "My First Post"
date: 2025-02-07T15:55:52+08:00
draft: true
---
    • title: The title of your blog post. Change "My First Post" to something more descriptive.
    • date: The date of your post. You can modify this.
    • draft: true: This post is currently marked as a draft. Hugo will not publish drafts by default unless you use the -D or --buildDrafts flag when generating your site.

    Edit the front matter and add some content below the --- delimiters. For example:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

    ---
title: "Hello World! My First Hugo Post"
date: 2025-02-07T15:55:52+08:00
draft: false
---

Welcome to my Hugo blog!

This is my first post. I'm excited to start blogging with Hugo and share my thoughts and experiences.

You can write content in Markdown, and Hugo will convert it into a static website.

Let's explore more features in the next posts!

    Important: Change draft: true to draft: false to publish your post (or keep it true if you don’t want it published yet).

  3. View your post locally: Start the Hugo server again:

    1

    hugo server -D

    Visit http://localhost:1313/posts/my-first-post/ in your browser. You should see your first blog post!

Push site to Github

Now that you have a basic Hugo site, let’s push it to Github so you can host it with Cloudflare Pages.

  1. Initialize Git repository (if not already done): hugo new site should initialize a Git repository, but if not, run:

    1

    git init

  2. Add and commit your files:

    1
2

    git add .
git commit -m "feat: initial commit with Hugo site and Ananke theme"

  3. Create a repository on Github:

    • Go to Github and log in to your account.
    • Click the “+” button in the top right corner and select “New repository”.
    • Choose a repository name (e.g., hugo-blog).
    • Select “Public” or “Private” as desired.
    • You can leave “Initialize this repository with:” options unchecked.
    • Click “Create repository”.

  4. Link local repository to your Github repository: Copy the repository URL from your newly created Github repository page. It will look something like https://github.com/your-username/hugo-blog.git. Then, in your terminal, run:

    1

    git remote add origin <your-github-repository-url>

    Replace <your-github-repository-url> with the URL you copied.

  5. Push your local repository to Github:

    1

    git push -u origin main

    This will push your Hugo site files to your Github repository. You may be prompted to log in to your Github account.

  6. (Optional) Create a .gitignore file: To prevent unnecessary files from being pushed to your repository (like the public folder which will be generated by Cloudflare Pages), create a file named .gitignore in the root of your project and add the following lines:

    1
2

    public/
themes/*/resources/_gen/

    Then, commit this .gitignore file:

    1
2
3

    git add .gitignore
git commit -m "chore: add .gitignore file"
git push origin main

Host the site using Cloudflare Pages

Cloudflare Pages is a great service for hosting static websites for free, and it integrates seamlessly with Github.

  1. Sign up for Cloudflare and go to Cloudflare Pages:

    • Go to Cloudflare and sign up for a free account if you don’t have one already.
    • Once logged in, navigate to “Pages” in the Cloudflare dashboard.

  2. Create a new Cloudflare Pages project:

    • Click the “Create a new project” button.
    • Click “Connect to Git”.

  3. Connect to Github and authorize Cloudflare Pages:

    • Select “Github” as the Git provider.
    • You may be asked to authorize Cloudflare Pages to access your Github repositories. Grant the necessary permissions.
    • Choose the Github repository you created for your Hugo blog (e.g., hugo-blog).
    • Click “Begin setup”.

  4. Configure build settings:

    • Framework preset: Select “Hugo”.
    • Build command: This should be automatically filled in as hugo. If not, enter hugo.
    • Publish directory: This should be automatically filled in as public. If not, enter public.
    • Environment variables (Optional): You usually don’t need to set environment variables for a basic Hugo setup.
    • Click “Save and Deploy”.

  5. Wait for deployment: Cloudflare Pages will now automatically build and deploy your Hugo site from your Github repository. This process might take a few minutes. You can monitor the build progress in the Cloudflare Pages dashboard.

  6. Access your site: Once deployment is complete, Cloudflare Pages will provide you with a *.pages.dev subdomain where your site is live. You can find this URL in the project overview in the Cloudflare Pages dashboard. Click on it to visit your live Hugo blog!

  7. (Optional) Set up a custom domain: To use your own domain name (e.g., www.your-blog.com):

    • In your Cloudflare Pages project dashboard, go to “Custom domains”.
    • Enter your custom domain name.
    • Cloudflare will provide instructions on how to update your DNS records at your domain registrar to point to Cloudflare. Follow these instructions.
    • Once DNS propagation is complete (this can take some time), your Hugo blog will be accessible at your custom domain. Cloudflare Pages automatically handles SSL certificates for your custom domain as well.
© 2024 - 2025 Jerry's Blog
~~~Thank you for visiting~~~

Theme Stack designed by Jimmy