Hugo Congo Static Site Build Workflow ·

Table of Contents

Installation and Setup #

Step 1 - Install Dependencies (macOS) #

Install the required tools: Git (extended), 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 tooling for custom styling:
```
npm install -D tailwindcss postcss autoprefixer
```

Step 2 - Create the Hugo Site (Local) #

Create a new Hugo site named <site-name> and initialize a local Git repository:
```
hugo new site <site-name>
cd <site-name>

git init
git branch -M main
```

Step 3 - Create the GitHub Repository (Remote) #

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

Step 4 - Connect the Local Repository to GitHub #

Link the local repository to GitHub and push the initial commit:

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

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

Step 5 - Install the Congo Theme (Hugo Module) #

Initialize the Hugo module:

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

Add the Congo theme:

mkdir -p config/_default

cat <<'EOF' > config/_default/module.toml
[[imports]]
path = "github.com/jpanther/congo/v2"
EOF

Start the development server (the theme will be downloaded automatically):
```
hugo server
```
Visit: http://localhost:1313
Remove the default Hugo configuration file:
```
rm hugo.toml
```
Copy Congo’s default configuration files (excluding module.toml) from this link into config/_default/.

Step 6 - Add `.gitignore` and Commit Changes #

Create and populate the .gitignore file:

touch .gitignore

cat <<'EOF' >> .gitignore
# Generated files by hugo
public/
/resources/_gen/

# Temporary lock file while building
.hugo_build.lock

# Other
_backup/
**/.DS_Store
EOF

Commit and push the changes:

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

Step 7 - Deploy to GitHub Pages #

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

Update the Git remote URL:

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

Add a GitHub Actions workflow by creating the directory .github/workflows/ and copying the workflow file of this link into .github/workflows/.
```
mkdir -p .github/workflows
```
Enable deployment using GitHub Pages with GitHub Actions, following the official guide: Publishing with a custom GitHub Actions workflow.
Commit and deploy the site:
```
git add .
git commit -m "Deploy Hugo site"
git push
```
Site URL: https://<username>.github.io/

Configuration and Contents Updates #

Step 1 - Update Configuration Files #

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

Step 2 - Add 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.

Step 3 - Add 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.

Step 4 - Add 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

Step 5 - Add `tailwind.config.js` #

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