Sam Hugo Theme

Sam (Call me Sam) is a simple and minimalist theme for the Hugo static site generator that turns a configurable list of navigation links into a typography-focused home page and provides content, post, and image-gallery templates.

What is Sam Hugo theme?

Sam is a Hugo theme created by Victoria Drake and released under the Apache License 2.0. It accepts a Hugo site's configuration and page bundles as input and produces a content-focused website with a stylized index page, list and single pages, posts, and responsive image galleries. The theme runs on the extended version of Hugo and uses Hugo Pipes to compile and autoprefix Sass styles.

Key Features

• Custom index page — The home page is a list of navigation links defined in the [[params.mainMenu]] entries in config.toml; the same list appears in the footer of single content pages.
• Image gallery layout — Set type: "gallery" in the front matter of a Page Bundle _index.md and Sam builds a responsive CSS grid from the images; options include maxWidth, clickablePhotos, and keepAspectRatio.
• Video background — Configure looping background video in config.toml with one or more sources, a poster image, and an optional overlay color (default rgba(0, 0, 0, 0.4)).
• Share-ready metadata — Pages include Open Graph and Twitter Card metadata that can be customized per page via front matter and globally in config.toml.
• Syntax highlighting — Code blocks in posts are highlighted to support developer-focused writing.
• Hugo Pipes integration — Styles are written in Sass files under assets/sass/; building with extended Hugo compiles, autoprefixes, and minifies them, and requires the npm packages postcss, postcss-cli, and autoprefixer.
• Version compatibility — Sam is tested with Hugo versions down to 0.49.2 and can be installed as a Hugo module (Go 1.12+), a git clone, or a git submodule.

Who should use Sam?

• Hugo developers who want a clean, typography-first theme for a personal site or portfolio without a complex layout.
• Photographers and visual artists who need a simple gallery page built directly from image files in a Page Bundle.
• Writers and bloggers who prioritize readable content and want a minimal home page listing their main sections.

Use cases

• Personal homepage: Showcase your name and link to your blog, photography, about page, or external profiles using only the main menu entries in config.toml.
• Gallery portfolio: Drop images into a Page Bundle, set type: "gallery" in the _index.md front matter, and Sam generates a responsive CSS grid gallery with optional click-to-full-size photos.
• Branded content site: Add a custom footer, background video, and Open Graph/Twitter metadata to give a site a tailored feel while keeping the template lightweight.

How does Sam work?

Install the theme by cloning the repository into themes/sam, adding it as a git submodule, or declaring it as a Hugo module with hugo mod get github.com/victoriadrake/hugo-theme-sam. Copy config.toml from the exampleSite, set the theme line, and adapt [[params.mainMenu]] entries to shape the index page. Then create content with hugo new page.md or hugo new posts/your-post-title.md; the gallery type automatically processes any valid Page Bundle when type: "gallery" is set in its _index.md.

FAQ

Is Sam free to use?

Yes, Sam is open source under the Apache License 2.0, which permits personal and commercial use with attribution and license preservation.

What are Sam's requirements?

Sam requires the extended version of Hugo, which includes Hugo Pipes and PostCSS support. You also need Node.js to install postcss, postcss-cli, and autoprefixer globally or inside the exampleSite.

How do I create an image gallery?

Place all gallery images in a Page Bundle, create an _index.md with type: "gallery", and optionally set title, url, maxWidth, clickablePhotos, and keepAspectRatio. Sam's gallery template renders the page automatically.

Can I add a video background?

Yes, define [[params.videoBackground.sources]] entries in config.toml with a source file and type (e.g., video/mp4), set a poster image, and optionally an overlay color. Sam uses the first source as a fallback and loops the video on the home page.

Does Sam work with older Hugo versions?

The theme is tested with Hugo versions as far back as 0.49.2. For the latest features, the theme author recommends using the newest extended Hugo release.