Sam is a Simple and Minimalist theme for Hugo. It lets you categorize and showcase your content the way you want to.
Focused on content and typography, the stylized index page is really just a list of navigation links that you can set in your config.toml
. This versatile design is limited only by your imagination, as you can make it say anything you like. Here are some ideas.
- Showcase content
- Content-focused page templates for list pages, single pages, and posts
- A responsive CSS grid gallery page that renders from images in your Page Bundle
- Customize
- Custom navigation menu set via
config.toml
- Custom footer text
- Custom background video via
config.toml
- Custom navigation menu set via
- Developer-approved
- Syntax highlighting
- Share-ready pages with Open Graph and Twitter metadata you can customize in
config.toml
and page front-matter - Effortless use of Hugo Pipes to generate CSS from Sass files
- Tested for compatibility with Hugo versions as far back as
0.49.2
- Use a more appealing and interactive gallery
- Add a nice 404 page
- Remove dependency to google fonts by adding the fonts to the repository
- use justify sytle for normal text in markdown
- some small style changes
Requires the extended version of Hugo. You can find installation instructions here (latest version recommended). Here's a handy Bash function for downloading a specific Hugo version.
Extended Hugo's PostCSS requires JavaScript packages to compile the styles for this theme. If you're seeing an error like this:
Error: Error building site: POSTCSS failed to transform "css/main.css"
Install the required packages globally using npm
. You'll need postcss
, postcss-cli
, and autoprefixer
.
npm i -g postcss postcss-cli autoprefixer
If you're new to Node.js and npm, learn how to install and use npm here. It is recommended that you use a version manager for your Node.js installation, such as nvm
.
Note: If you are using Hugo as a snap app, the above two Node.js packages have to be installed locally inside exampleSite
.
cd exampleSite/
npm i postcss postcss-cli autoprefixer
Run from the root of your Hugo site:
$ git clone https://github.com/mfg92/hugo-theme-sam themes/sam
Alternatively you can include this repository as a git submodule. This makes it easier to update this theme if you have your Hugo site in git as well. For this you need to run:
$ git submodule add https://github.com/mfg92/hugo-theme-sam.git themes/sam
NOTE: This theme depends on https://github.com/mfg92/hugo-shortcode-gallery. So make sure you get that theme component in your themes folder as well.
From the exampleSite, copy config.toml
to the root folder of your Hugo site and change the fields as you like. There are helpful hints in the file.
Run:
hugo new page.md
Where page
can be anything you like. A contact page, a bio, dates for your upcoming world tour... Anything!
In config.toml
, customize the entries for [[params.mainMenu]]
however you like. You can have as many or as few entries as you like. You can even include external links.
This list comprises the index page and part of the navigation menu at the bottom of single content pages. Here's an example:
[[params.mainMenu]]
link = "/photography"
text = "photography"
[[params.mainMenu]]
link = "/posts"
text = "writing"
[[params.mainMenu]]
link = "/about"
text = "who dis?"
Use Hugo's built-in server to see your site in action as you make changes.
hugo serve -t sam
Visit localhost:1313
in your browser to see a live preview of your site.
To create a new post, run:
hugo new posts/your-post-title.md
To create an image gallery, place all the files you want included in your Page Bundle. The directory structure might then look like this:
content/
└── gallery/
├── _index.md
├── file_1.jpg
├── file_2.jpg
└── file_3.jpg
To automatically generate a gallery from the images, set type: "gallery"
in the front-matter of _index.md
. You can also set other options for the gallery:
- The gallery
title
- The page link with
url
- The
maxWidth
of the resized images - Whether you want the images to link to the full size files, with
clickablePhotos
- You can keep the orignal aspect ratio of the images in the grid with
keepAspectRatio
Here is an example of a gallery's _index.md
:
---
title: "Portraits"
type: "gallery"
url: "/portrait-gallery"
maxWidth: "800x"
clickablePhotos: true
keepAspectRatio: false
---
In order to create more than one gallery, create multiple Page Bundles with images and type: "gallery"
defined in the _index.md
front matter. For example:
content/
├── gallery/
| ├── _index.md
| ├── file_1.jpg
| ├── file_2.jpg
| └── file_3.jpg
|
└── portfolio/
├── _index.md
├── file_1.jpg
├── file_2.jpg
└── file_3.jpg
That's it! Sam's gallery layout template will automatically build the page from your images.
To change the default home page background to a looping video, you need to set a list of video sources and optionally an overlay color (default: rgba(0, 0, 0, 0.4)
).
Here is an example configuration of config.toml
:
[[params.videoBackground.sources]]
source = "/background.mp4" # Your video file
type = "video/mp4"
poster = "/background.jpg" # The image to show when the video isn't playing
[params.videoBackground]
overlay = "rgba(0, 0, 0, 0.4)" # optional
And here is a screenshot of what that might look like:
This theme uses Hugo Pipes to compile, autoprefix, and minify its CSS styles from the included Sass files.
To make changes to the CSS, edit the Sass files located in assets/sass/
, then build your site using extended Hugo, which you can obtain from Hugo Releases.
If when building you do not see the changes you have done, make sure to build your website with the --ignoreCache
flag, otherwise Hugo will
attempt to use its own cached Sass files.
You can run the built-in server to preview the site as you make changes to the Sass files!
If you have a question or get stuck, please open an issue for help and to help those who come after you. The more information you can provide, the better!
Pull requests for bug fixes and enhancements are welcome! Please ensure you first read about contributing to this project.
Open source themes like this one would not be possible without some amazing contributors. Thank you!
Copyright (C) 2018-2021 Victoria Drake
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.