Building a Static Website with Hugo and Congo ·

Table of Contents

Installation (macOS) #

Install required tools: Git (extended version), Go, Node.js, and Hugo:

brew install git go node hugo

(Optional) Verify the installations:

git --version
go version
node -v
hugo version

Install TailwindCSS and related tools:

npm install -D tailwindcss postcss autoprefixer

Create Hugo Website #

Create a new Hugo site:

hugo new site <site-name>
cd <site-name>

Initialize Git:

git init
git branch -M main

Create an empty GitHub repository named <site-name>.

Connect the local repository:

git remote add origin https://github.com/<username>/<site-name>.git

Commit and push the initial changes:

git add .
git commit -m "Initial commit"
git push -u origin main

Add Congo Theme #

Initialize Hugo Modules:

hugo mod init github.com/<username>/<site-name>

Create module.toml to configure the Congo theme:

mkdir -p config/_default
touch config/_default/module.toml

Add the following configuration to config/_default/module.toml:

[[imports]]
path = "github.com/jpanther/congo/v2"

Start the local server:

hugo server

The Congo theme will be downloaded automatically.

Visit: http://localhost:1313

Remove the default Hugo configuration:

rm hugo.toml

Copy Congo’s default configuration files (excluding module.toml) from https://github.com/jpanther/congo/tree/dev/config/_default to config/_default/.

Create .gitignore:

touch .gitignore

Add Hugo-generated and temporary files:

# Files generated by Hugo
public/
/resources/_gen/

# Temporary lock file while building
.hugo_build.lock

# Other
_backup/
**/.DS_Store

Commit and push changes:

git add .
git commit -m "Set up Hugo module and Congo theme"
git push

Deploy to GitHub Pages #

Rename the repository from <site-name> to <username>.github.io.

Update the Git remote:

git remote set-url origin https://github.com/<username>/<username>.github.io.git

(Optional) Verify the remote URL:

git remote -v

Create the GitHub Actions workflow directory:

mkdir -p .github/workflows

Copy the Hugo workflow into .github/workflows/.

Enable deployment using GitHub Pages with GitHub Actions: Publishing with a custom GitHub Actions workflow.

Commit and push deployment changes:

git add .
git commit -m "Deploy Hugo site"
git push

Website: https://<username>.github.io/

Customize Website #

Configuration #

Modify hugo.toml:
Section From To
– # baseURL = "https://your_domain.com/" baseURL = "https://<username>.github.io/"

Section	From	To
–	`# baseURL = "https://your_domain.com/"`	`baseURL = "https://<username>.github.io/"`

Modify params.toml:

Section	From	To
–	`colorScheme = "congo"` `enableSearch = false` `enableCodeCopy = false`	`colorScheme = "fruit"` `enableSearch = true` `enableCodeCopy = true`
`header`	`# logo = "img/logo.jpg"` `# logoDark = "img/dark-logo.jpg"`	`logo = "img/logo.jpg"` `logoDark = "img/dark-logo.jpg"`
`footer`	`showAppearanceSwitcher = false`	`showAppearanceSwitcher = true`
`homepage`	`layout = "page"`	`layout = "profile"`

Modify languages.en.toml:

Section	From	To
–	`title = "Congo"` `# copyright = "Copy, _right?_ 🤔"`	`# title = "Home"` `copyright = "Copyright © 2026. All rights reserved."`
`params.author`	`# name = "Your name here"` `# image = "img/author.jpg"`	`name = "Fangfei Li"` `image = "img/author.jpg"`

Modify menus.en.toml: View example

Assets #

Add the assets/ directory to store images, stylesheets, and a custom color scheme (View Example):

assets/
├── img/
│   ├── author.jpg
│   ├── logo.jpg
│   └── dark-logo.jpg
└── css/
    ├── schemes/
    │   └── fruit.css           # Custom color scheme
    └── custom.css

The contents of the directory css/ are sourced from this link.

Layouts #

Add the layouts/ directory for custom templates and overrides (View Example):
```
layouts/
├── _partials/                  # Reusable partial templates
└── list.html                   # Custom list page template
```
The contents of the directory _partials/ are sourced from this link. Remove logo.html to enable the logo.

Static Files #

Add the static/ directory for fonts, icons, and downloadable resources (View Example):

static/
├── files/                      # Downloadable resources
├── FiraCode-Regular.ttf        # Fira Code font
├── favicon.ico
├── favicon-32x32.png
├── favicon-16x16.png
├── apple-touch-icon.png
├── android-chrome-512x512.png
├── android-chrome-192x192.png
└── site.webmanifest

Tailwind Configuration #

The file tailwind.config.js is sourced from this link.