# Hugo Reference Hugo is the world's fastest static site generator. It builds sites in milliseconds and supports advanced content management features. ## Installation ### Windows ```powershell # Using Chocolatey choco install hugo-extended # Using Scoop scoop install hugo-extended # Using Winget winget install Hugo.Hugo.Extended ``` ### macOS ```bash # Using Homebrew brew install hugo ``` ### Linux ```bash # Debian/Ubuntu (snap) snap install hugo --channel=extended # Using package manager (may not be latest) sudo apt-get install hugo # Or download from https://gohugo.io/installation/ ``` ## Quick Start ### Create New Site ```bash # Create site hugo new site mysite cd mysite # Initialize git and add theme git init git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke echo "theme = 'ananke'" >> hugo.toml # Create first post hugo new content posts/my-first-post.md # Start development server hugo server -D ``` ### Directory Structure ``` mysite/ ├── archetypes/ # Content templates │ └── default.md ├── assets/ # Assets to process (SCSS, JS) ├── content/ # Markdown content │ └── posts/ ├── data/ # Data files (YAML, JSON, TOML) ├── i18n/ # Internationalization ├── layouts/ # Templates │ ├── _default/ │ ├── partials/ │ └── shortcodes/ ├── static/ # Static files (copied as-is) ├── themes/ # Themes └── hugo.toml # Configuration ``` ## CLI Commands | Command | Description | |---------|-------------| | `hugo new site ` | Create new site | | `hugo new content ` | Create content file | | `hugo` | Build to `public/` | | `hugo server` | Start dev server | | `hugo mod init` | Initialize Hugo Modules | | `hugo mod tidy` | Clean up modules | ### Build Options ```bash # Basic build hugo # Build with minification hugo --minify # Build with drafts hugo -D # Build for specific environment hugo --environment production # Build to custom directory hugo -d ./dist # Verbose output hugo -v ``` ### Server Options ```bash # Start with drafts hugo server -D # Bind to all interfaces hugo server --bind 0.0.0.0 # Custom port hugo server --port 8080 # Disable live reload hugo server --disableLiveReload # Navigate to changed content hugo server --navigateToChanged ``` ## Configuration (hugo.toml) ```toml # Basic settings baseURL = 'https://example.com/' languageCode = 'en-us' title = 'My Hugo Site' theme = 'ananke' # Build settings [build] writeStats = true # Markdown configuration [markup] [markup.goldmark] [markup.goldmark.extensions] definitionList = true footnote = true linkify = true strikethrough = true table = true taskList = true [markup.goldmark.parser] autoHeadingID = true autoHeadingIDType = 'github' [markup.goldmark.renderer] unsafe = false [markup.highlight] style = 'monokai' lineNos = true # Taxonomies [taxonomies] category = 'categories' tag = 'tags' author = 'authors' # Menus [menus] [[menus.main]] name = 'Home' pageRef = '/' weight = 10 [[menus.main]] name = 'Posts' pageRef = '/posts' weight = 20 # Parameters [params] description = 'My awesome site' author = 'John Doe' ``` ## Front Matter Hugo supports TOML, YAML, and JSON front matter: ### TOML (default) ```markdown +++ title = 'My First Post' date = 2025-01-28T12:00:00-05:00 draft = false tags = ['hugo', 'tutorial'] categories = ['blog'] author = 'John Doe' +++ Content here... ``` ### YAML ```markdown --- title: "My First Post" date: 2025-01-28T12:00:00-05:00 draft: false tags: ["hugo", "tutorial"] --- Content here... ``` ## Templates ### Base Template (_default/baseof.html) ```html {{ .Title }} | {{ .Site.Title }} {{ partial "head.html" . }} {{ partial "header.html" . }}

{{ partial "footer.html" . }} ``` ### Single Page (_default/single.html) ```html {{ define "main" }}

{{ end }} ``` ### List Page (_default/list.html) ```html {{ define "main" }}

{{ end }} {{ end }} ``` ## Shortcodes ### Built-in Shortcodes ```markdown {{< figure src="/images/photo.jpg" title="My Photo" >}} {{< youtube dQw4w9WgXcQ >}} {{< gist user 12345 >}} {{< highlight go >}} fmt.Println("Hello") {{< /highlight >}} ``` ### Custom Shortcode (layouts/shortcodes/alert.html) ```html

``` Usage: ```markdown {{< alert type="warning" >}} **Warning:** This is important! {{< /alert >}} ``` ## Content Organization ### Page Bundles ``` content/ ├── posts/ │ └── my-post/ # Page bundle │ ├── index.md # Content │ └── image.jpg # Resources └── _index.md # Section page ``` ### Accessing Resources ```html {{ $image := .Resources.GetMatch "image.jpg" }} {{ with $image }}

{{ end }} ``` ## Hugo Pipes (Asset Processing) ### SCSS Compilation ```html {{ $styles := resources.Get "scss/main.scss" | toCSS | minify }} ``` ### JavaScript Bundling ```html {{ $js := resources.Get "js/main.js" | js.Build | minify }} ``` ## Taxonomies ### Configure ```toml [taxonomies] tag = 'tags' category = 'categories' ``` ### Use in Front Matter ```markdown +++ tags = ['go', 'hugo'] categories = ['tutorials'] +++ ``` ### List Taxonomy Terms ```html {{ range .Site.Taxonomies.tags }} {{ .Page.Title }} ({{ .Count }}) {{ end }} ``` ## Multilingual Sites ```toml defaultContentLanguage = 'en' [languages] [languages.en] title = 'My Site' weight = 1 [languages.es] title = 'Mi Sitio' weight = 2 ``` ## Troubleshooting | Issue | Solution | |-------|----------| | Page not found | Check `baseURL` configuration | | Theme not loading | Verify theme path in config | | Raw HTML not showing | Set `unsafe = true` in goldmark config | | Slow builds | Use `--templateMetrics` to debug | | Module errors | Run `hugo mod tidy` | | CSS not updating | Clear browser cache or use fingerprinting | ## Resources - [Hugo Documentation](https://gohugo.io/documentation/) - [Hugo Themes](https://themes.gohugo.io/) - [Hugo Discourse](https://discourse.gohugo.io/) - [GitHub Repository](https://github.com/gohugoio/hugo) - [Quick Reference](https://gohugo.io/quick-reference/)