Introduction #

Hugo is a fast, flexible static site generator perfect for digital gardens, blogs, and documentation. Vercel offers seamless, free hosting with continuous deployment from your Git repository. This guide walks you through creating a Hugo site and deploying it to Vercel, following best practices for content structure, SEO, and maintainability.

Prerequisites #

• Git installed
• Go (for installing Hugo)
• Hugo (extended version recommended)
• GitHub or GitLab account
• Vercel account

Create a New Hugo Site #

Open your terminal and run:

1hugo new site my-hugo-site
2cd my-hugo-site

2. Add a Theme #

Browse Hugo Themes and pick one. For example, to use the “Ananke” theme:

1git init
2git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
3echo 'theme = "ananke"' >> hugo.toml

Customize Site Configuration #

Edit hugo.toml to set your site title, baseURL, and other settings:

1title = "My Hugo Site"
2baseURL = "https://your-vercel-domain.vercel.app/"
3theme = "ananke"
4languageCode = "en-us"

Add Content #

Create your first post:

1hugo new posts/hello-world.md

Edit the generated file in content/posts/hello-world.md and add your content. Use front matter for metadata.

5. Preview Locally #

Start the Hugo development server:

1hugo server -D

Visit http://localhost:1313 to preview your site.

Push to GitHub or GitLab #

Initialize a repository (if you haven’t already):

1git add .
2git commit -m "Initial Hugo site"
3git branch -M main
4git remote add origin https://github.com/yourusername/my-hugo-site.git
5git push -u origin main

Deploy to Vercel #

1. Go to Vercel and sign in.
2. Click New Project and import your Hugo repository.
3. Vercel auto-detects Hugo. If not, set:
   • Framework Preset: Hugo
   • Build Command: hugo
   • Output Directory: public
4. Click Deploy.

Vercel will build and deploy your site. You’ll get a live URL like https://my-hugo-site.vercel.app/.

(Recommended) Add a vercel.json Config File #

To ensure Vercel uses the correct Hugo and Go versions and build command, add a vercel.json file to your project root:

1{
2  "build": {
3    "env": {
4      "HUGO_VERSION": "0.148.2",
5      "GO_VERSION": "1.24.5"
6    }
7  },
8  "buildCommand": "hugo --gc --minify"
9}

Explanation:

• HUGO_VERSION and GO_VERSION specify the exact versions used for the build, ensuring compatibility.
• buildCommand runs Hugo with garbage collection and minification for optimized builds.

Custom Domain (Optional) #

• In your Vercel dashboard, go to your project > Settings > Domains.
• Add your custom domain and follow the DNS instructions.

Continuous Deployment #

Every push to your Git repository will trigger an automatic redeploy on Vercel.

Best Practices for Digital Gardens #

• Use clear, descriptive front matter for all posts.
• Organize content in /content/posts/, /content/notes/, etc.
• Add tags and categories for discoverability.
• Use internal links: [See my other post](https://www.fernandohermida.com/posts/complete-guide-to-mcp/)
• Optimize images using Hugo’s built-in processing.
• Write evergreen content and update regularly.

Troubleshooting #

• Build errors? Check the Vercel build logs for missing dependencies or misconfigurations.
• Theme issues? Ensure your theme is included as a submodule and referenced in hugo.toml.
• 404s? Make sure your content files have correct front matter and are in the right folders.

See Also #

• Hugo Official Docs
• Vercel Hugo Deployment Guide

Content maturity: evergreen 🌲