Hugo
Overview
The EdgeOne Makers console has built-in, comprehensive support for the Hugo static site generator framework. When you deploy a Hugo project to Makers, the system automatically detects the project type, manages the Hugo version, executes the build, and caches the build artifacts, enabling zero-configuration continuous integration and deployment for Hugo sites.
Core Feature
Automatically identify Hugo projects with no need for additional declaration.
Built-in Hugo Extended version, supports SCSS/SASS compilation.
Flexible version management, supports specifying any Hugo version.
Automatically cache build artifacts to speed up repeated builds.
Quick Start
Project Requirements
Make sure your Hugo project root directory contains any one of the following configuration files or directories:
Configuration File | Description |
hugo.toml / hugo.yaml / hugo.json | Hugo new version configuration format (recommend) |
config.toml / config.yaml / config.json | Hugo legacy version configuration format |
config/_default/ directory | Hugo multi-environment configuration mode |
The system automatically determines whether the project is a Hugo project through detection of these files.
Deployment Steps
1. Creating a Hugo project
hugo new site my-sitecd my-site
2. Add
edgeone.json configuration file (optional but recommended)// ./edgeone.json{"buildCommand": "hugo --minify","outputDirectory": "public"}
3. Develop related webpages locally
4. Push code to Git repository
5. Associate repository and deploy in Makers console
The system automatically detects the Hugo project and completes the build deployment.
Hugo Version Management
Hugo Extended v0.147.5 is pre-installed as the default version, supporting SCSS/SASS compilation.
Version Priority
Determine the Hugo version to use by the following priority (from high to low):
Priority | Method | Description |
1 (highest) | edgeone.json's hugoVersion field | project-level configuration, recommended for use |
2 | HUGO_VERSION environment variable | runtime environment variable |
3 (min) | pre-installed version | v0.147.5 |
Method One: Specify Version via edgeone.json (Recommended)
Add the
hugoVersion field to edgeone.json in the project root directory:{"hugoVersion": "0.139.0","buildCommand": "hugo --minify","outputDirectory": "public"}
Note:
Version numbers can have or omit the
v prefix, such as "0.139.0" and "v0.139.0".Method Two: Specify Version through Environment Variables
Add environment variables in the project settings of the Makers console:
HUGO_VERSION=0.139.0
Method Three: Use Default Version
If no version is specified, the system will use the pre-installed Hugo Extended v0.147.5.
Build Configuration
Build Command
In
edgeone.json, configure the Hugo build command via buildCommand:{"buildCommand": "hugo --minify","outputDirectory": "public"}
Commonly used Hugo build command example:
Command | Description |
hugo | default build |
hugo --minify | Build and compress HTML/CSS/JS |
hugo --minify --gc | Build, compress, and clean up unused resources |
hugo -e production | Build with production environment settings |
hugo --baseURL https://example.com | Designated site BaseURL |
Output Directory
Hugo outputs to the
public directory by default. Please set outputDirectory to public (or your custom output directory) in edgeone.json.Building Cache
Makers automatically manages the Hugo build cache, requiring no manual configuration.
Caching Mechanism
Cache directory:
resources/_gen.Cached content: Hugo image processing results, SCSS/SASS compilation products, and generated resources.
Recovery timing: Automatically recover last cache before each build starts.
Saving timing: Automatically save after each build completes.
Caching Effect
Leverage the
resources/_gen cache to skip processed images and compiled style files during repeated builds, significantly reducing build time.Supported Configuration Format
Hugo supports multiple configuration file formats, all of which Makers can correctly identify:
Single File Configuration
my-hugo-site/├── hugo.toml # recommend├── content/├── layouts/└── static/
Legacy Version File Configuration
my-hugo-site/├── config.toml # legacy format, still supported├── content/├── layouts/└── static/
Multi-Environment Configuration (Directory Method)
my-hugo-site/├── config/│ └── _default/│ ├── hugo.toml│ ├── params.toml│ └── menus.toml├── content/├── layouts/└── static/
FAQs
1. How to confirm system detection of your Hugo project
The build log will display the
Hugo project detected. notification and show the currently used Hugo version, such as:Using Hugo v0.147.5
2. What to Do When a Build Error Notification Shows an Unsupported Version of Hugo for a Feature
Check the earliest version required by your Hugo theme or template, and specify the corresponding version in
edgeone.json:{"hugoVersion": "0.128.0"}
3. What to Do When Hugo Installation Failure (Exit Code 14) Occurs
Possible causes:
The designated Hugo version number is invalid (Release for this version does not exist).
Network issue caused download failure
Solution:
Confirm the version number is correct. All available versions can be viewed on the Hugo Releases page.
If it is a temporary network issue, just trigger build again.
4. Why uses Hugo Extended version
The Hugo Extended edition has built-in compilation support for SCSS/SASS, a feature on which most Hugo themes depend. Makers always install the Extended edition to ensure compatibility with mainstream themes.
5. Does a Hugo Project Need package.json
Not required. The testing of the Go project is independent of the Node.js ecosystem. The system detects through the Hugo configuration file (such as
hugo.toml). However, if your project uses both npm packages (such as PostCSS), it can contain both package.json.6. How to Clear Build Cache
If you encounter a build exception due to caching, you can add cleaning steps to the build command:
{"buildCommand": "rm -rf resources/_gen && hugo --minify","outputDirectory": "public"}
Complete Configuration Example
Minimum Configuration
The project root directory just needs to contain a Hugo configuration file (such as
hugo.toml), and the system will use the default version and default build behavior.Recommended Configuration
edgeone.json:{"hugoVersion": "0.147.5","buildCommand": "hugo --minify","outputDirectory": "public"}
Advanced Configuration (Multi-Environment)
edgeone.json:{"hugoVersion": "0.147.5","buildCommand": "hugo --minify -e production","outputDirectory": "public"}
- Overview
- Core Feature
- Quick Start
- Hugo Version Management
- Build Configuration
- Building Cache
- Supported Configuration Format
- FAQs
- 1. How to confirm system detection of your Hugo project
- 2. What to Do When a Build Error Notification Shows an Unsupported Version of Hugo for a Feature
- 3. What to Do When Hugo Installation Failure (Exit Code 14) Occurs
- 4. Why uses Hugo Extended version
- 5. Does a Hugo Project Need package.json
- 6. How to Clear Build Cache
- Complete Configuration Example