1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
# [Call me Sam: a theme for Hugo](https://victoria.dev/hugo-theme-sam/)
[](https://app.netlify.com/sites/hugo-theme-sam/deploys)
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.
## Features
- 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](https://gohugo.io/content-management/organization/#page-bundles)
- Customize
- Custom navigation menu set via `config.toml`
- Custom footer text
- Developer-approved
- Syntax highlighting
- Share-ready pages with [Open Graph](https://gohugo.io/templates/internal/#open-graph) and [Twitter](https://gohugo.io/templates/internal/#twitter-cards) 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`
## Quick start
## Requirements
- Extended version of [Hugo](https://gohugo.io/getting-started/installing/) (latest version recommended)
Extended Hugo's [PostCSS](https://gohugo.io/hugo-pipes/postcss/) requires JavaScript packages to compile the styles for this theme. If you're seeing an error like this:
```text
Error: Error building site: POSTCSS failed to transform "css/main.css"
```
You can install the required packages using `npm`:
- [postcss-cli](https://github.com/postcss/postcss-cli):`npm install -g postcss-cli`
- [autoprefixer](https://github.com/postcss/autoprefixer): `npm install -g autoprefixer`
[Learn how to install and use npm here](https://www.npmjs.com/get-npm).
Note: If you are using [Hugo as a snap app](https://snapcraft.io/hugo), the above two Node.js packages have to be [installed locally inside `exampleSite`](https://gohugo.io/hugo-pipes/postcss/).
```sh
cd exampleSite/
npm install postcss-cli
npm install autoprefixer
```
## 1. Get the theme
Run from the root of your Hugo site:
```sh
git clone https://github.com/victoriadrake/hugo-theme-sam.git themes/sam
```
Alternatively you can include this repository as a [git submodule](https://git-scm.com/book/de/v1/Git-Tools-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:
```sh
git submodule add https://github.com/victoriadrake/hugo-theme-sam.git themes/sam
```
### 2. Configure your site
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.
### 3. Create pages
Run:
```sh
hugo new page.md
```
Where `page` can be anything you like. A contact page, a bio, dates for your upcoming world tour... Anything!
### 4. Design your main menu and index page
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:
```toml
[[params.mainMenu]]
link = "/photography"
text = "photography"
[[params.mainMenu]]
link = "/posts"
text = "writing"
[[params.mainMenu]]
link = "/about"
text = "who dis?"
```
## Preview your site locally
Use Hugo's built-in server to see your site in action as you make changes.
```sh
hugo serve -t sam
```
Visit `localhost:1313` in your browser to see a live preview of your site.
## Posts
To create a new post, run:
```sh
hugo new posts/your-post-title.md
```
## Image gallery
To create an image gallery, place all the files you want included in your [Page Bundle](https://gohugo.io/content-management/organization/#page-bundles). The directory structure might then look like this:
```sh
content/
└── gallery/
├── _index.md
├── file_1.jpg
├── file_2.jpg
└── file_3.jpg
```
To automagically 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`:
```yaml
---
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:
```text
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 automagically build the page from your images.
## Editing the theme
This theme uses [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/) 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](https://github.com/gohugoio/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!
## Contributing
Pull requests for bug fixes and enhancements are welcome.
Open source themes like this one would not be possible without some amazing __[contributors](https://github.com/victoriadrake/hugo-theme-sam/graphs/contributors)__. Thank you!
## License
Copyright (C) 2018-2020 Victoria Drake
Licensed under [Apache-2.0](https://github.com/victoriadrake/hugo-theme-sam/blob/master/LICENSE)
|
