Hugo Best Practices is an open-source documentation repository by Sebastian Pech that collects concrete configuration, content organization, and performance guidelines for building sites with Hugo, the static site generator.
What is Hugo Best Practices?
This GitHub repository is a community checklist and guide, not a downloadable theme itself. It takes the form of a structured README that teaches how to set up a Hugo site: content structure, archetypes, configuration, asset pipelines, and deployment. It runs on Hugo (any version from around 0.60 onward) and is maintained by Sebastian Pech, who also publishes three companion themes — Bootstrap-BP, Materialize-BP, and a Bootstrap-BP startpage — based on these practices.
Key Features
- Content organization — Place images next to the index.md file so Hugo can generate resized thumbnails; the README shows a folder structure with posts like 0001-firstpost.
- Git and CI/CD — Recommends version control with Git and deployment via webhook or Jenkins, plus rsync deployment scripts included in the repository.
- Archetypes and permalinks — Example archetype for posts includes front matter for title, author, type, date, featured_image, draft, categories, tags, and description, with permalink patterns like /:year/:month/:slug/.
- Hugo Pipes asset pipeline — Shows how to use minify, fingerprint, slice, toCSS, and postCSS on files in the assets folder to generate minified, integrity-hashed CSS and JS bundles.
- Image processing — Uses the featured_image front matter parameter and .Resize "800x" to create fixed-width images from the original source kept in the page bundle.
- Caching and .htaccess — An example .htaccess file covers redirects, compression, caching, SSL, HSTS, Content Security Policy, error documents, and WordPress migration rules.
- Schema.org structured data — Includes a partial that outputs JSON-LD for BlogPosting with fields like headline, description, author, publisher, dates, URL, word count, and keywords.
- External links — For Hugo 0.60+ and the Goldmark parser, a render-link.html shortcode is provided (in the linked hugo-shortcodes collection) to add target="_blank" and rel="noopener noreferrer" to external http(s) links.
Who is it for?
- Hugo site developers — follow the content organization, archetype, and permalink guidance to set up a new blog or portfolio.
- Hugo theme authors — use the CSS/JS asset pipeline and Schema.org partial examples to add production-ready processing and SEO to a theme.
- Technical site owners — apply the .htaccess rules and the Front-End Checklist to improve caching, SSL, security, and performance on an existing Apache-hosted site.
What can you do with it?
- Launch a new Hugo blog — copy the archetype and permalink configuration to get consistent post URLs like /2024/05/slug and automatic draft mode.
- Build a faster theme — combine multiple CSS and JS files into single minified, fingerprinted bundles with the slice and concat technique shown.
- Publish automatically — set up a webhook-triggered deployment so every git push rebuilds the site and syncs files with rsync.
- Add SEO and structured data — integrate the Schema.org BlogPosting partial and submit the generated sitemap.xml to Google Search Console and Bing Webmaster Tools.
How does the guide work?
Navigate the table of contents to jump to a practice (content, CI, assets, images, caching, SEO). Each section contains a short explanation, a concrete example, and links to official Hugo documentation. The repository also includes deployment scripts and an example .htaccess file to adapt to your own site.
Pricing
Free — this is a public, open-source GitHub repository with no paid tiers or licensing fees.
Alternatives
- Awesome Hugo — a curated list of Hugo resources maintained by theNewDynamic; it aggregates links to themes and tools rather than providing step-by-step practices.
- Official Hugo documentation — the primary reference for Hugo configuration and templates; this repository complements it with field-tested examples.
FAQ
Does this guide work with the latest Hugo version?
The guide specifically addresses the Hugo 0.60 update that switched the default markdown parser from Blackfriday to Goldmark, and it includes an update for image processing order in SEO templates. Most practices remain valid for current Hugo versions, and the example config calls out options like canonical URLs and sitemap settings.
What are the companion themes?
Sebastian Pech publishes three themes based on these practices: Bootstrap-BP, Materialize-BP, and a Bootstrap-BP startpage. Each implements the content organization, asset pipeline, and structured data recommendations from the guide, and can be used as a starting point for a Hugo site.
Where should CSS and JavaScript files live?
To use Hugo Pipes for minification and fingerprinting, files must be placed in the assets folder rather than static. The README shows retrieving them with resources.Get, concatenating with slice, and outputting a single minified file with a sha512 integrity hash.
Is the .htaccess file safe to copy?
The README warns that you must understand every rule before applying it, especially the Content-Security-Policy which can break pages relying on external sources. The file covers redirects, compression, caching, SSL, HSTS, error documents, and WordPress migration rules.
What image processing does the guide show?
Keep high-resolution originals inside a page bundle and reference them in the featured_image front matter parameter. Hugo's image processing function .Resize '800x' then generates a thumbnail at 800 pixels wide, linked via a permalink in the img tag.
