{{ .Title }}
{{ .Summary }}
{{ .name }} -- {{ .role }}
{{ end }} ``` --- ## 5. Common Tasks ### 5.1 Creating a Blog ```bash hugo new project my-blog cd my-blog git init git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke ``` `hugo.toml`: ```toml baseURL = "https://myblog.com/" title = "My Blog" theme = "ananke" paginate = 5 [permalinks] [permalinks.page] posts = "/blog/:year/:month/:slug/" [params] author = "Your Name" ``` Create posts: ```bash hugo new content posts/hello-world.md hugo new content posts/second-post.md ``` ### 5.2 Creating a Documentation Site ```bash hugo new project my-docs cd my-docs ``` Structure content as nested sections: ``` content/ _index.md docs/ _index.md getting-started/ _index.md installation.md configuration.md guides/ _index.md basics.md advanced.md reference/ _index.md api.md cli.md ``` Use `weight` in front matter to control page ordering within sections: ```yaml --- title: "Installation" weight: 1 --- ``` ### 5.3 Adding Search (JSON Index) Enable JSON output for the home page: ```toml [outputs] home = ["HTML", "RSS", "JSON"] ``` Create `layouts/_default/index.json`: ```go-html-template {{- $pages := where .Site.RegularPages "Type" "not in" (slice "page") -}} [ {{- range $i, $p := $pages }} {{- if $i }},{{ end }} { "title": {{ $p.Title | jsonify }}, "url": {{ $p.RelPermalink | jsonify }}, "content": {{ $p.Plain | jsonify }}, "tags": {{ $p.Params.tags | jsonify }}, "date": {{ $p.Date.Format "2006-01-02" | jsonify }} } {{- end }} ] ``` Then use a client-side search library (Fuse.js, Lunr.js, Pagefind) to query `index.json`. ### 5.4 Adding an RSS Feed RSS is enabled by default for the home page and sections. Customize in config: ```toml [services] [services.rss] limit = 20 ``` Custom RSS template: create `layouts/_default/rss.xml`. ### 5.5 Creating Custom Archetypes Create `archetypes/posts.md`: ```markdown --- title: "{{ replace .File.ContentBaseName "-" " " | title }}" date: {{ .Date }} draft: true tags: [] categories: [] description: "" cover: image: "" alt: "" --- ## Introduction ## Body ## Conclusion ``` Now `hugo new content posts/my-post.md` uses this template. Directory-based archetypes are also supported. Create `archetypes/posts/` with an `index.md` and any resource files -- `hugo new content` copies the entire directory as a page bundle. ### 5.6 Syntax Highlighting Hugo uses Chroma for server-side syntax highlighting. #### Inline Highlighting ````markdown ```python def hello(): print("Hello, world!") ``` ```` #### Highlight Shortcode with Options ```markdown {{}} func main() { fmt.Println("Hello") fmt.Println("World") } {{}} ``` #### Generate a Custom Chroma Stylesheet ```bash hugo gen chromastyles --style=dracula > static/css/syntax.css hugo gen chromastyles --style=github --highlightStyle="bg:#f0f0f0" ``` Then in config: ```toml [markup.highlight] noClasses = false ``` ### 5.7 Image Processing Recipes #### Responsive Images ```go-html-template {{ $img := resources.Get "images/hero.jpg" }} {{ $small := $img.Resize "480x" }} {{ $medium := $img.Resize "960x" }} {{ $large := $img.Resize "1440x" }}{{ .Summary }}
Last modified: {{ .GitInfo.AuthorDate.Format "January 2, 2006" }}
By: {{ .GitInfo.AuthorName }}
Hash: {{ .GitInfo.Hash }}
``` > [!WARNING] > `enableGitInfo` requires the full Git history. If you're using shallow clones > in CI (e.g., `actions/checkout` with default `depth: 1`), set `fetch-depth: 0` > to get the complete history, or Git info will be missing/incorrect. ### 5.18 Front Matter Cascade Apply front matter values to all descendant pages: ```yaml # content/docs/_index.md --- title: "Documentation" cascade: type: docs layout: single sidebar: true --- ``` All pages under `content/docs/` inherit these values unless they override them. ### 5.19 Page Resources Access resources from page bundles: ```go-html-template {{ $img := .Resources.GetMatch "hero.*" }} {{ with $img }}Sorry, the page you're looking for doesn't exist.
Go home {{ end }} ``` Most static hosts serve `404.html` automatically for missing routes. ### 5.22 Converting Front Matter Formats ```bash # Convert all front matter to TOML hugo convert toTOML # Convert to YAML hugo convert toYAML # Convert to JSON hugo convert toJSON # Write to a different directory (preserve originals) hugo convert toYAML --output converted/ # Convert even unsafe content hugo convert toTOML --unsafe ``` ### 5.23 Importing from Jekyll ```bash hugo import jekyll /path/to/jekyll-site /path/to/hugo-site # Force overwrite existing destination hugo import jekyll /path/to/jekyll-site /path/to/hugo-site --force ``` This converts Jekyll content and front matter to Hugo format. Manual cleanup is usually needed for Liquid templates. ### 5.24 Generating CLI Documentation ```bash # Generate Markdown documentation for all Hugo commands hugo gen doc --dir docs/cli/ # Generate man pages hugo gen man --dir man/ ``` ### 5.25 Sections and Content Types Hugo's content type system maps sections to layouts: ``` content/ posts/ # Type: "posts" -> layouts/posts/ docs/ # Type: "docs" -> layouts/docs/ events/ # Type: "events" -> layouts/events/ ``` Override in front matter: ```yaml --- type: "docs" layout: "tutorial" --- ``` ### 5.26 Menu Management #### In Config ```toml [[menus.main]] name = "Blog" pageRef = "/posts" weight = 10 [menus.main.params] icon = "blog" [[menus.main]] name = "GitHub" url = "https://github.com/yourname" weight = 100 [menus.main.params] external = true ``` #### In Front Matter ```yaml --- title: "About" menus: main: weight: 30 name: "About Us" --- ``` #### Nested Menus ```toml [[menus.main]] identifier = "products" name = "Products" weight = 20 [[menus.main]] parent = "products" name = "Widget A" pageRef = "/products/widget-a" weight = 1 ``` ### 5.27 Render Hooks Customize how Markdown elements render by creating templates in `layouts/_default/_markup/`: ``` layouts/_default/_markup/ render-link.html # Custom link rendering render-image.html # Custom image rendering render-heading.html # Custom heading rendering render-codeblock.html # Custom code block rendering render-codeblock-mermaid.html # Mermaid diagram rendering ``` Example `render-image.html`: ```go-html-template {{ $img := .Page.Resources.GetMatch .Destination }} {{ with $img }} {{ $small := .Resize "600x" }}{{ .title }}
Stars: {{ $data.stargazers_count }}
{{ end }} ``` > [!CAUTION] > Remote data fetching is subject to Hugo's security policy. By default, > only GET and POST methods are allowed. The URL must match the configured > `security.http.urls` patterns. If a fetch fails silently, check your > `security` configuration. ### 5.32 PostCSS / Tailwind CSS Integration Install dependencies: ```bash npm init -y npm install tailwindcss @tailwindcss/typography postcss autoprefixer ``` `postcss.config.js`: ```javascript module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } } ``` In your template: ```go-html-template {{ $css := resources.Get "css/main.css" | postCSS | minify | fingerprint }} ``` Or use Tailwind CSS v4+ directly (Hugo has built-in `tailwindcss` binary support via the `css.TailwindCSS` template function). ### 5.33 JavaScript Bundling with js.Build ```go-html-template {{ $opts := dict "targetPath" "js/bundle.js" "minify" true "target" "es2020" "externals" (slice "react" "react-dom") "defines" (dict "process.env.NODE_ENV" "\"production\"") "format" "esm" "sourceMap" "inline" }} {{ $js := resources.Get "js/main.js" | js.Build $opts }} ``` `js.Build` uses esbuild internally -- it handles ESM imports, TypeScript, JSX/TSX, tree-shaking, and code splitting. ### 5.34 Mounting Directories ```toml [module] [[module.mounts]] source = "content" target = "content" [[module.mounts]] source = "static" target = "static" [[module.mounts]] source = "layouts" target = "layouts" [[module.mounts]] source = "data" target = "data" [[module.mounts]] source = "assets" target = "assets" [[module.mounts]] source = "i18n" target = "i18n" [[module.mounts]] source = "archetypes" target = "archetypes" # Mount a directory from a module [[module.mounts]] source = "node_modules/@fortawesome/fontawesome-free/webfonts" target = "static/webfonts" ``` ### 5.35 Multi-host Server Configuration ```toml [server] [[server.headers]] for = "/**" [server.headers.values] X-Frame-Options = "DENY" Content-Security-Policy = "default-src 'self'" [[server.redirects]] from = "/old/**" to = "/new/:splat" status = 301 [[server.redirects]] from = "/api/**" to = "https://api.example.com/:splat" status = 200 # Proxy (rewrite, not redirect) ``` --- ## 6. Troubleshooting ### 6.1 Build Errors #### "Error: module 'X' not found" Hugo cannot resolve a module dependency. ```bash # Re-fetch modules hugo mod get # Clean and re-fetch hugo mod clean --all hugo mod get ``` If using `go.sum`, ensure it's committed. Try `hugo mod tidy` to remove stale entries. #### "Error building site: TOCSS: failed to transform" Sass/SCSS compilation failed. Common causes: 1. **Missing Dart Sass**: Install `dart-sass` or `sass-embedded` and ensure it's in PATH. 2. **Wrong edition**: You need the **extended** edition of Hugo for built-in LibSass. 3. **Invalid SCSS syntax**: Check the file referenced in the error message. ```bash # Verify Hugo edition hugo version # Should show "+extended" # Set Dart Sass path explicitly export DART_SASS_BINARY=/usr/local/bin/sass ``` #### "Error: POSTCSS: failed to transform" PostCSS processing failed. ```bash # Ensure Node.js dependencies are installed npm install # Verify postcss is available npx postcss --version # Check postcss.config.js exists in project root ``` #### "Error building site: ... timed out" Page generation exceeded the timeout (default 30 seconds). ```toml # Increase timeout in hugo.toml timeout = "120s" ``` This can happen with complex template logic, heavy image processing, or large `resources.GetRemote` calls. #### "WARN duplicate target path" Two pages resolve to the same URL. ```bash hugo --printPathWarnings ``` Fix by adjusting `slug`, `url`, or `permalinks` in the conflicting pages. #### "Template metrics: slow templates" ```bash hugo --templateMetrics --templateMetricsHints ``` Look for templates with high cumulative time. Common culprits: uncached `resources.GetRemote`, unoptimized image processing inside loops, repeated `.GetPage` calls. ### 6.2 Server Issues #### Port Already in Use ```bash # Use a different port hugo server -p 8080 # Or find and kill the process using port 1313 lsof -ti :1313 | xargs kill ``` #### Live Reload Not Working 1. Check that `--disableLiveReload` is not set. 2. Browser extensions (ad blockers, privacy tools) may block WebSocket connections. 3. If behind a reverse proxy, ensure WebSocket upgrade headers are forwarded. 4. Try `--disableFastRender` for a full rebuild on each change. #### File Watching Not Working (Network Drives / VMs) ```bash hugo server --poll 700ms ``` Polling mode uses periodic filesystem checks instead of inotify/fsevents, which don't work on network-mounted filesystems. #### Server Not Accessible from LAN ```bash hugo server --bind 0.0.0.0 -b http://192.168.1.100:1313/ ``` The default bind address (`127.0.0.1`) only accepts local connections. ### 6.3 Content Issues #### Page Not Appearing Check these common causes: 1. **Draft**: `draft: true` in front matter -- use `-D` flag or set `draft: false`. 2. **Future date**: `date` is in the future -- use `-F` flag or fix the date. 3. **Expired**: `expiryDate` has passed -- use `-E` flag or remove/extend the date. 4. **Wrong section**: File is not in the expected content directory. 5. **Missing `_index.md`**: Section pages require `_index.md` to be listed. 6. **Disabled kind**: Check `disableKinds` in config. #### Front Matter Not Parsed Ensure delimiters are correct: - YAML: three dashes `---` on their own line, top and bottom - TOML: three plus signs `+++` on their own line, top and bottom - JSON: opening `{` and closing `}` (first and only JSON block) No blank lines before the opening delimiter. #### Taxonomy Pages Missing Ensure taxonomies are configured: ```toml [taxonomies] tag = "tags" category = "categories" ``` If you override `[taxonomies]`, you must include ALL taxonomies -- even the defaults (`tags`, `categories`) if you want to keep them. #### Unicode / Accent Issues in URLs ```toml removePathAccents = true ``` #### Markdown Not Rendering Check that the file has a supported extension (`.md`, `.markdown`, `.mdown`). For raw HTML in Markdown: ```toml [markup.goldmark.renderer] unsafe = true ``` ### 6.4 Template Issues #### "Can't evaluate field X in type Y" You're accessing a variable that doesn't exist on the object. Common mistakes: - `.Params.title` vs `.Title` (params are lowercase) - `.Site.Params.x` vs `.Params.x` (site params vs page params) - Missing `with` or `if` guard around optional values #### Partial Not Found Partials must live in `layouts/partials/`. The call omits the directory: ```go-html-template {{ partial "header.html" . }} ``` Corresponds to `layouts/partials/header.html`. #### Template Changes Not Reflected In server mode with fast render: ```bash hugo server --disableFastRender ``` Or restart the server. Some template changes (especially in `baseof.html`) require a full rebuild. ### 6.5 Image Processing Issues #### "Image not found" or Nil Pointer Images must be in `assets/` (for global resources) or in a page bundle (for page resources). Files in `static/` cannot be processed. ```go-html-template {{ $img := resources.Get "images/hero.jpg" }} {{ $img := .Resources.GetMatch "hero.*" }} ``` #### EXIF / Image Metadata Warnings Some images trigger decode warnings (related to [#14758](https://github.com/gohugoio/hugo/issues/14758)). These are non-fatal warnings. To suppress: ```toml ignoreLogs = ["warning-image-metadata"] ``` #### WebP / AVIF Not Working Requires the **extended** edition. Verify with `hugo version` (must show `+extended`). ### 6.6 Module Issues #### "go.sum: not found" ```bash hugo mod tidy ``` #### Module Cache Stale ```bash hugo mod clean --all hugo mod get -u ``` #### Vendor Directory Issues ```bash # Re-vendor all dependencies hugo mod vendor # Build using vendored modules (ignore _vendor when this glob matches) hugo --ignoreVendorPaths "**" ``` ### 6.7 Performance Issues #### Slow Builds 1. **Profile templates**: `hugo --templateMetrics --templateMetricsHints` 2. **Reduce image processing**: Cache processed images, limit resize operations. 3. **Avoid `.Site.Pages` in templates**: Use `.Site.RegularPages` or scope queries. 4. **Enable caching**: Configure `[caches]` section. 5. **Limit taxonomies**: Disable unused taxonomies. 6. **Use `--gc`**: Clean up unused cache files. ```bash hugo --gc --minify ``` #### Memory Issues ```bash export HUGO_MEMORYLIMIT=4096 # MB hugo --gc ``` #### Parallel Processing ```bash export HUGO_NUMWORKERMULTIPLIER=2 # Default: 1 (num CPUs) ``` ### 6.8 Deployment Issues #### "deploy" Command Not Found The `deploy` command requires Hugo to be built with the `withdeploy` tag. Binary releases may not include it. Build from source: ```bash go install -tags withdeploy github.com/gohugoio/hugo@latest ``` #### Base URL Wrong in Production Ensure `baseURL` matches your production domain exactly: ```toml baseURL = "https://www.example.com/" ``` Or override at build time: ```bash hugo -b https://www.example.com/ ``` #### Minification Breaks JavaScript Hugo's minifier can reorder `const` initializations ([#14760](https://github.com/gohugoio/hugo/issues/14760)). If your JS breaks after minification: ```toml [minify] disableJS = true ``` Or use `js.Build` with its own `minify` option instead, which uses esbuild (more JavaScript-aware). #### SVG Minification Breaks Alpine.js The SVG minifier can corrupt Alpine.js `x-bind` attributes ([#14669](https://github.com/gohugoio/hugo/issues/14669)). Workaround: ```toml [minify] disableSVG = true ``` ### 6.9 Hugo New Ignores Environment The `hugo new` command does not respect the `-e` flag for environment selection ([#13722](https://github.com/gohugoio/hugo/issues/13722)). It always uses the default configuration. Workaround: manually apply environment-specific values after creation. ### 6.10 Syntax Highlighting Style Mismatch The `github` Chroma style may not match actual GitHub rendering for dark mode ([#14730](https://github.com/gohugoio/hugo/issues/14730)). Use `github-dark` explicitly for dark themes: ```bash hugo gen chromastyles --style=github-dark > static/css/syntax-dark.css ``` ### 6.11 :contentbasename Broken for Taxonomies The `:contentbasename` permalink token has issues with taxonomy pages since v0.153 ([#14325](https://github.com/gohugoio/hugo/issues/14325)). Workaround: use `:slug` or `:title` tokens for taxonomy permalinks. ### 6.12 js.Build Output Varies by Output Format Different output formats may produce different `js.Build` results ([#14254](https://github.com/gohugoio/hugo/issues/14254)). Ensure consistent `js.Build` options across all output formats, or use resource caching. ### 6.13 Cache :resourceDir Token Resolution The `:resourceDir` token in cache paths may not resolve as expected ([#14165](https://github.com/gohugoio/hugo/issues/14165)). Use explicit absolute paths in cache configuration if you encounter issues: ```toml [caches.assets] dir = "/tmp/hugo-cache/assets" maxAge = -1 ``` ### 6.14 Commands Apply Config from All Environments Certain commands may unexpectedly apply configuration from all environment directories rather than just the target environment ([#14763](https://github.com/gohugoio/hugo/issues/14763)). Workaround: keep environment-specific overrides minimal and non-conflicting. ### 6.15 Stacktrace Lost on Panic When Hugo panics during template execution, the stacktrace may not point to the template that caused the issue ([#13811](https://github.com/gohugoio/hugo/issues/13811)). Use `--panicOnWarning` during debugging to catch issues earlier, and `--logLevel debug` for more context. ### 6.16 Language/Role/Version in Filenames Content filenames with language, role, or version suffixes may not be parsed as expected ([#14756](https://github.com/gohugoio/hugo/issues/14756)). Prefer using front matter for these metadata fields rather than encoding them in the filename. ### 6.17 Build Lock File Conflicts Hugo creates `.hugo_build.lock` during builds. If you encounter lock conflicts in CI: ```bash hugo --noBuildLock ``` ### 6.18 CORS Issues with Dev Server The dev server doesn't set CORS headers by default. Use server configuration: ```toml [server] [[server.headers]] for = "/api/**" [server.headers.values] Access-Control-Allow-Origin = "*" ``` ### 6.19 Config File Not Found Hugo looks for `hugo.toml`, `hugo.yaml`, or `hugo.json` in the project root (or the path specified by `--source`). Common issues: 1. **Wrong directory**: Run Hugo from the project root. 2. **Wrong filename**: Hugo does not support `config.toml` in recent versions. Rename to `hugo.toml`. 3. **Config directory**: If using `config/`, ensure `_default/hugo.toml` exists. ```bash # Specify config explicitly hugo --config my-config.toml # Specify config directory hugo --configDir my-config/ ``` ### 6.20 Emoji Shortcodes Not Rendering ```toml enableEmoji = true ``` Without this, `:smile:` renders as literal text. ### 6.21 i18n Translation Warnings ```bash hugo --printI18nWarnings ``` Shows missing translation keys. Provide translations in `i18n/` files. ### 6.22 Assets Not Found After Moving to Modules When migrating from `git submodule` themes to Hugo Modules, asset paths may change. Verify mounts: ```bash hugo config mounts ``` ### 6.23 Ignoring Cache for Fresh Builds ```bash hugo --ignoreCache ``` Forces Hugo to bypass all caches and rebuild from scratch. ### 6.24 Content Not Updating in Server Mode Fast render mode only rebuilds changed pages. If related pages don't update: ```bash hugo server --disableFastRender ``` Or press Ctrl+C and restart the server. ### 6.25 "Security policy violation" Errors Hugo restricts which external programs can run. If you get a security policy error: ```toml [security.exec] allow = ["^dart-sass$", "^go$", "^git$", "^npx$", "^postcss$", "^tailwindcss$", "^your-tool$"] ``` Add your tool's binary name to the allow list. ### 6.26 Exif Jsonify Type Info Calling `jsonify` on `.Exif` data may produce unexpected type information in the output ([#10345](https://github.com/gohugoio/hugo/issues/10345)). Extract specific EXIF fields individually rather than serializing the entire `.Exif` object. --- ## 7. FAQ ### General **Q: What is Hugo?** A: Hugo is a static site generator written in Go. It takes content files (Markdown, AsciiDoc, etc.) and templates, and produces a complete static website that can be served by any web server or CDN. **Q: How fast is Hugo?** A: Hugo routinely builds thousands of pages per second. A site with 10,000+ pages typically builds in under 10 seconds. Build speed depends on template complexity, image processing, and content volume -- not Hugo itself. **Q: What's the difference between Hugo standard and extended editions?** A: The extended edition adds Sass/SCSS compilation (LibSass), WebP encoding, and regex-based Unicode normalization. Most users should install the extended edition. **Q: What content formats does Hugo support?** A: Markdown (via Goldmark -- the default), AsciiDoc (via Asciidoctor), Org Mode, reStructuredText, and Pandoc. Markdown is by far the most common. **Q: What front matter formats does Hugo support?** A: YAML (delimited by `---`), TOML (delimited by `+++`), and JSON (wrapped in `{}`). YAML is the most common convention. **Q: What license is Hugo released under?** A: Apache License 2.0. **Q: What are the page kinds Hugo supports?** A: `home`, `page`, `section`, `taxonomy`, `term`, `RSS`, `sitemap`, `robotsTXT`, and `404`. ### Installation **Q: Do I need Go installed to use Hugo?** A: No. Pre-built binaries are standalone. You only need Go if building from source or using Hugo Modules (Go handles module resolution behind the scenes, but Hugo bundles the necessary tooling). **Q: How do I check my Hugo version?** A: `hugo version` or `hugo env` for full environment details. **Q: How do I upgrade Hugo?** A: Use your package manager (`brew upgrade hugo`, `choco upgrade hugo-extended`, etc.) or download the latest binary from the releases page. **Q: What Go version do I need to build Hugo from source?** A: Go 1.25.0 or later. ### Content **Q: What's the difference between `index.md` and `_index.md`?** A: `_index.md` (with underscore) is a **branch bundle** -- it defines a section list page and can have child pages. `index.md` (without underscore) is a **leaf bundle** -- it defines a single page and its resources. **Q: How do I create a page at a specific URL?** A: Use the `url` front matter field: ```yaml --- url: /custom/path/ --- ``` **Q: How do I exclude a page from listings?** A: Set `_build` options in front matter: ```yaml --- _build: list: never render: always --- ``` **Q: How do I set a custom slug?** A: Use the `slug` front matter field: ```yaml --- slug: "my-custom-slug" --- ``` **Q: Can I use HTML in Markdown files?** A: By default, raw HTML in Markdown is stripped. Enable it: ```toml [markup.goldmark.renderer] unsafe = true ``` **Q: How do I add metadata to pages without rendering them?** A: Use headless bundles: ```yaml # content/data-pages/my-data/index.md --- headless: true --- ``` Headless pages are accessible in templates but don't generate output files. **Q: How do I control the order of pages in a section?** A: Use `weight` in front matter (lower weight = earlier in list). Default ordering is by date (newest first). **Q: How does the `` divider work?** A: Place `` in your content to define a manual summary split point. Everything above the divider becomes the `.Summary`; everything below is only shown on the full page. **Q: What is a headless bundle?** A: A leaf bundle with `headless: true` in front matter. It is processed (so you can access its resources in templates) but does not produce an output page or appear in any listing. ### Configuration **Q: Can I use multiple configuration files?** A: Yes. Use the config directory approach (`config/_default/`, environment overrides) or pass multiple files: `--config a.toml,b.toml`. **Q: How do I set config values via environment variables?** A: Prefix with `HUGO_` and use underscores for nesting: `HUGO_PARAMS_AUTHOR="Jane"` sets `params.author`. **Q: What's the default environment for `hugo` vs `hugo server`?** A: `hugo` (build) defaults to `production`. `hugo server` defaults to `development`. Override with `-e` or `HUGO_ENVIRONMENT`. **Q: What config file names does Hugo support?** A: `hugo.toml`, `hugo.yaml`, or `hugo.json`. The old `config.toml` name is no longer auto-detected in recent versions. **Q: How do I use a config directory instead of a single file?** A: Create a `config/` directory with `_default/hugo.toml` as the base, and add environment-specific subdirectories (`production/`, `staging/`, etc.) with overlay files. Hugo merges them automatically. ### Themes **Q: Where do I find Hugo themes?** A: The official theme directory is at [themes.gohugo.io](https://themes.gohugo.io/). Themes can also be installed as Hugo Modules from any Git repository. **Q: How do I override a theme template?** A: Create the same file path in your project's `layouts/` directory. Hugo uses your version instead of the theme's. For example, to override the theme's `layouts/_default/single.html`, create `layouts/_default/single.html` in your project. **Q: Can I use multiple themes?** A: Yes. Specify multiple themes in config: ```toml theme = ["theme-base", "theme-override"] ``` Later themes override earlier ones (right wins). **Q: How do I create my own theme?** A: `hugo new theme mytheme` scaffolds a theme skeleton in `themes/mytheme/`. **Q: What is the theme lookup order?** A: Hugo checks your project's `layouts/` first, then themes in reverse order (last theme listed wins). This applies to templates, partials, shortcodes, and archetypes. ### Deployment **Q: What do I need to deploy a Hugo site?** A: Just a web server or static file host. Hugo outputs plain HTML/CSS/JS. Any host that serves static files works: Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3, a VPS with nginx, etc. **Q: Does Hugo have a built-in deploy command?** A: Yes, `hugo deploy` supports S3, GCS, and Azure Blob Storage. It requires the `withdeploy` build tag (included in some binary releases). Configure targets in `[deployment]` in your config. **Q: How do I handle redirects?** A: Hugo supports `aliases` in front matter (generates HTML redirect files). For server-side redirects, use your hosting platform's native redirect mechanism. **Q: How do I set up continuous deployment?** A: Connect your Git repository to Netlify, Vercel, Cloudflare Pages, or GitHub Actions. Set the build command to `hugo --minify` and the publish directory to `public`. Pin the Hugo version via environment variable. ### Performance **Q: Why is my build slow?** A: Common causes: heavy image processing, complex template logic (especially in loops), excessive `resources.GetRemote` calls, unused taxonomy generation. Profile with `hugo --templateMetrics --templateMetricsHints`. **Q: How do I speed up image processing?** A: Use image caching (enabled by default), process images once and reference the result, avoid processing in loops. Consider generating image variants at fewer breakpoints. **Q: What is `--gc` and when should I use it?** A: The `--gc` flag runs garbage collection after the build, removing unused cached files (processed images, resources). Use it in CI or when disk space is a concern. **Q: How can I reduce memory usage during builds?** A: Set `HUGO_MEMORYLIMIT` (in MB), reduce image processing, use `--gc`, and avoid loading entire site page collections in templates when a scoped query will do. ### Modules **Q: What are Hugo Modules?** A: Hugo Modules use Go Modules to manage project dependencies. Themes, content, data, assets, layouts -- anything can be a module. They replace `git submodule` for dependency management. **Q: Do I need Go installed for Hugo Modules?** A: Hugo ships with Go module support, but having Go installed helps for module initialization (`hugo mod init`) and management. **Q: How do I update a module?** A: `hugo mod get -u github.com/owner/module` or `hugo mod get -u` for all. **Q: How do I pin a module to a specific version?** A: `hugo mod get github.com/owner/module@v1.2.3`. The version is recorded in `go.mod`. ### Multilingual **Q: How do I set up a multilingual site?** A: Configure `[languages]` in your config with weight, language name, and any language-specific parameters. Create translated content with filename suffixes (`.fr.md`) or directory structure (`content/fr/`). **Q: How do I translate menus and strings?** A: Use `i18n/` files for UI strings. Menus can be defined per-language in config under each `[languages.xx]` section. **Q: How does Hugo determine the default language?** A: Via `defaultContentLanguage` in config (defaults to `"en"`). Content files without a language suffix are assigned to the default language. ### Templating **Q: What templating language does Hugo use?** A: Go's `html/template` and `text/template` packages, with Hugo-specific functions and methods added on top. **Q: What is `baseof.html`?** A: The base template (`layouts/_default/baseof.html`) defines the overall HTML structure. Other templates define named blocks (`{{ block "main" . }}`) that fill in sections of the base template. **Q: How do I access site-wide parameters in templates?** A: Use `.Site.Params.yourParam`. Define parameters under `[params]` in config. **Q: How do I pass variables to partials?** A: Pass a context (usually `.` for the current page) or a custom dict: ```go-html-template {{ partial "mypartial.html" (dict "page" . "color" "blue") }} ``` --- ## CLI Reference ### Global Flags These flags work with every Hugo command: | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--source` | `-s` | `.` | Filesystem path to read files from | | `--destination` | `-d` | `public` | Filesystem path to write files to | | `--environment` | `-e` | varies | Build environment | | `--config` | | auto-detected | Config file path | | `--configDir` | | `config` | Config directory path | | `--themesDir` | | `themes` | Path to themes directory | | `--quiet` | | `false` | Suppress non-error output | | `--logLevel` | | `warn` | Log level: debug, info, warn, error | | `--renderToMemory` | `-M` | `false` | Render to memory (no disk write) | | `--ignoreVendorPaths` | | | Glob pattern to ignore `_vendor` paths | | `--noBuildLock` | | `false` | Don't create `.hugo_build.lock` | | `--clock` | | | Override system clock (ISO 8601 format) | ### Build Flags These flags work with `hugo` and `hugo server`: | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--theme` | `-t` | config value | Theme(s) to use | | `--baseURL` | `-b` | config value | Root URL | | `--contentDir` | `-c` | `content` | Content directory | | `--layoutDir` | `-l` | `layouts` | Layout directory | | `--cacheDir` | | OS temp | Cache directory | | `--buildDrafts` | `-D` | `false` | Include drafts | | `--buildFuture` | `-F` | `false` | Include future content | | `--buildExpired` | `-E` | `false` | Include expired content | | `--enableGitInfo` | | `false` | Add Git info to pages | | `--cleanDestinationDir` | | `false` | Remove dest files not from static | | `--minify` | | `false` | Minify output | | `--watch` | `-w` | `false` | Watch for changes | | `--gc` | | `false` | Run cache cleanup after build | | `--ignoreCache` | | `false` | Bypass cache directory | | `--renderSegments` | | | Named segments to render | | `--disableKinds` | | | Page kinds to disable | | `--poll` | | | File watch poll interval | | `--templateMetrics` | | `false` | Display template timing metrics | | `--templateMetricsHints` | | `false` | Show template optimization hints | | `--forceSyncStatic` | | `false` | Copy all static files on change | | `--noTimes` | | `false` | Don't sync modification times | | `--noChmod` | | `false` | Don't sync permissions | | `--printI18nWarnings` | | `false` | Print missing i18n translations | | `--printPathWarnings` | | `false` | Print duplicate path warnings | | `--printUnusedTemplates` | | `false` | Warn on unused templates | | `--panicOnWarning` | | `false` | Panic on WARNING log entries | ### Server Flags These flags are specific to `hugo server`: | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--port` | `-p` | `1313` | Port to listen on | | `--bind` | | `127.0.0.1` | Interface to bind to | | `--liveReloadPort` | | `-1` (auto) | Live reload port | | `--disableLiveReload` | | `false` | Disable live reload | | `--disableFastRender` | | `false` | Full re-render on each change | | `--disableBrowserError` | | `false` | Don't show errors in browser | | `--navigateToChanged` | | `false` | Navigate to changed content | | `--renderStaticToDisk` | | `false` | Serve static from disk | | `--noHTTPCache` | | `false` | Disable HTTP caching | | `--tlsAuto` | | `false` | Auto-generate local TLS certs | | `--tlsCertFile` | | | TLS certificate file | | `--tlsKeyFile` | | | TLS key file | ### Command Reference | Command | Description | |---------|-------------| | `hugo` / `hugo build` | Build the site | | `hugo server` | Start development server with live reload | | `hugo server trust` | Install/uninstall local CA for TLS | | `hugo new content