Hugo Common commands
| Command | Description | Example usage |
|---|---|---|
hugo | Generate a static site and output to the public/directory | hugo --minify |
hugo server | Start the development server, default port 1313, real-time preview site | hugo server --bind 0.0.0.0 |
hugo new | Create a new content file, such as an article or page hugo new post/my-post.md | |
hugo version | Displays the current Hugo version information | hugo version |
hugo mod | Manage Hugo Modules (modular themes or dependencies) | hugo mod init github.com/user/repo |
hugo config | Displays the current configuration information | hugo config |
hugo env | Displays Hugo environment information (e.g., version, Go version) | hugo env |
hugo list | List content files (e.g., drafts, future articles) | hugo list drafts |
hugo check | Check the integrity of the content file | hugo check |
hugo --help | Displays Hugo command help | hugo --help |
Common Options:
- ‘–watch’: Monitors file changes (‘hugo server’ is enabled by default).
- ‘–ignoreCache’: ignores the cache and forces a rebuild.
- ‘–minify’: compresses output files (e.g. HTML, CSS, JS).
- ‘–debug’: displays debugging information.
Other important content
Config item (commonly used in ‘hugo.yaml’)
| CI | Description | Example value |
|---|---|---|
baseURL | The site root URL, which is used to generate an absolute link | https://www.test.com/ |
languageCode | The default language code is | en-us |
theme | The name of the topic used | hugo-theme-stack |
title | Site title | My Blog |
permalinks | Defines the URL structure of the content type | post: /p/:slug/ |
outputs | Specify the output format | for the page type home: ["HTML", "RSS", "JSON"] |
params | Custom parameters for the theme to use | sidebar.avatar: /img/avatar.png |
menu | Customize the navigation menu | main: [{name: "Home", url: "/"}] |
Front Matter
| Field | Description | Example value |
|---|---|---|
title | Article or page title | My First Post |
date | Release Date | 2025-03-28 |
draft | Whether it’s a draft (’true’ is not published) | false |
tags | Tag List | ["tech", "blog"] |
categories | Category List | ["Programming"] |
slug | Custom part of the URL | my-first-post |
Hugo Pipes (Resource Processing)
| Features | Description | Example usage |
|---|---|---|
resources. Get | Get resource files (e.g., images, SCSS) | {{ resources. Get "images/pic.jpg" }} |
Resize | Resize the image | {{ $img. Resize "300x" }} |
ToCSS | Compile SCSS to CSS | `{{ $css := resources. Get “scss/main.scss” |
Topic-related
- Installation Theme:
1git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/hugo-theme-stack
- Enable Theme: Set ’theme: hugo-theme-stack’ in ‘hugo.yaml’.
Commonly used Hugo topic tables
| Topic name | Link | Description |
|---|---|---|
| PaperMod | [github.com/adityatelange/hugo-PaperMod] (https://github.com/adityatelange/hugo-PaperMod) | Concise, responsive blog theme that supports dark mode, is easy to read, optimizes user experience, and is suitable for personal blogs |
| Stack | [github.com/CaiJimmy/hugo-theme-stack] (https://github.com/CaiJimmy/hugo-theme-stack) | Multi-purpose theme, blog-support, portfolio-supporting, with sidebar and commenting system (like Waline) for tech bloggers |
| Docsy | [github.com/google/docsy] (https://github.com/google/docsy) | Designed for technical documentation, multi-language support, integrated search and navigation, suitable for open source project documentation |
| Anatole | [github.com/lxndrblz/anatole] (https://github.com/lxndrblz/anatole) | Minimalist two-column theme for blogs and personal portfolios with an elegant, responsive layout |
| Book | [github.com/alex-shpak/hugo-book] (https://github.com/alex-shpak/hugo-book) | A concise documentation theme that mimics the style of a book, suitable for tutorials or knowledge base sites. |
| Hello Friend NG | [github.com/rhazdon/hugo-theme-hello-friend-ng] (https://github.com/rhazdon/hugo-theme-hello-friend-ng) | Simple blog theme, support dark/light mode switching, focus on typography and reading experience |
| Mainroad | [github.com/vimux/mainroad] (https://github.com/vimux/mainroad) | Magazine-style theme with responsive design for informative blogs or news sites |
| Coder | [github.com/luizdepra/hugo-coder] (https://github.com/luizdepra/hugo-coder) | A very simple page theme that is suitable for developers to display their bios and projects, and has a fast loading speed |
| Beautiful Hugo | [github.com/halogenica/beautifulhugo] (https://github.com/halogenica/beautifulhugo) | Multi-purpose blog theme with support for Disqus comments, social sharing, suitable for personal and professional blogs |
| Reveal-Hugo | [github.com/dzello/reveal-hugo] (https://github.com/dzello/reveal-hugo) | Reveal.js-based presentation theme for creating HTML slideshows. |
Folder description table in the Hugo root directory and theme directory
Hugo root folder
| Folders/Files | Description | Precautions |
|---|---|---|
archetypes/ | A content template directory that defines the default front matter | for new files such as ‘hugo new’ ‘default.md’ is included by default, and other templates can be customized |
assets/ | The resource file directory, which stores SCSS, images, etc., is processed by Hugo Pipes (e.g., compiling SCSS to CSS) | Support needs to be configured in ‘hugo.yaml’ (e.g. ‘assets.dir’). |
content/ | A directory of content files that holds Markdown files, organized by type (e.g. ‘content/post/’ for articles) | The file name determines the URL (e.g., ‘my-post.md’ -> ‘/post/my-post/’). |
data/ | A data file directory that holds YAML, JSON, or TOML files for dynamic data (such as navigation menu data). In the template by ‘. Site.Data’ access | |
layouts/ | Customize the template directory to override the theme’s default template | Priority is higher than templates of the same name in ’themes/’ |
public/ | The generated static site output directory, with the post-build content in this | Each run of ‘hugo’ empties and regenerates the |
static/ | Static file directories, which store images, CSS, JS, etc., are directly copied to the root directory of the site Output directly to ‘public/’ | , without Hugo processing |
themes/ | A theme directory that stores downloaded or custom themes (e.g. ‘hugo-theme-stack’). Enable | via the ’theme’ configuration |
hugo.yaml | Master profile, defining site settings (such as language, theme, URL, etc.) | YAML, TOML, JSON formats are supported |
Theme directory folder (’themes//’)
| Folders/Files | Description | Precautions |
|---|---|---|
archetypes/ | The theme provides a default content template that uses the | It can be overridden by the ‘archetypes/’ of the root directory |
assets/ | The theme’s resource file directory, which stores SCSS, images, etc., is handled by Hugo Pipes | Usually contains a style file for the theme (e.g. ‘main.scss’) |
layouts/ | The template directory of the theme, which defines the page rendering logic (e.g., ‘single.html’, ’list.html’). Can be overridden by the ’layouts/’ of the root directory | |
static/ | The static file directory of the theme, which stores CSS, JS, images, etc., is directly copied to the root directory of the site Output to ‘public/’, e.g. ‘static/img/’ -> ‘/img/’ | |
data/ | A data file directory for a topic that provides topic-specific data (such as menu configurations). In the template by ‘. Site.Data’ access | |
i18n/ | Internationalized file directory for multilingual translation files (e.g. ’en.yaml’, ‘zh-cn.yaml’) | Used to support multilingual sites |
README.md | Theme documentation with installation and usage guides It is recommended that you read carefully to understand the configuration requirements | |
theme.yaml | A topic metadata file that defines the topic name, author, minimum version, and so on Used in the Hugo Theme Management System to identify topics |
Illustrate:
- Folders in the root directory and the theme directory function similarly, but the configuration and file priority of the root directory takes precedence over the topic directory.
- The files in the theme directory are common templates and resources designed for the theme, which can be overwritten or extended by developers through the root directory.
Additional Notes
- How to choose a theme:
- Choose according to your needs: PaperMod or Stack for blogs, Docsy for documents, and Coder for resumes.
- Check Activity: See when it was last updated and how it was responded to on GitHub.
- Folder usage suggestions:
- Put custom images into ‘static/’ to avoid Hugo processing (e.g. no compression).
- Store SCSS files in ‘assets/’ to take advantage of Hugo Pipes’ compilation capabilities.
- Debugging Tips:**
- Run ‘hugo server –debug’ to see the file load and render logs.
- Use ‘hugo –printPathWarnings’ to check for path issues.