README.md
1 # Terminimal 2 3 [](https://github.com/pawroman/zola-theme-terminimal/actions/workflows/pages/pages-build-deployment) 4  5 6  7 8 See the live demo (of the default configuration) here: 9 https://pawroman.github.io/zola-theme-terminimal/ 10 11 Tested with Zola v0.17.2. Please note that earlier versions might not work because of breaking changes across Zola versions. 12 13 #### Fork disclaimer 14 15 This theme is a fork (not a port) of "Terminal" Hugo theme 16 by Radosław Kozieł (aka. panr): 17 https://github.com/panr/hugo-theme-terminal 18 19 Many thanks for that outstanding original theme, Radek! 20 21 For more information about this fork and the differences to the original theme, please see: 22 [Changes compared to the original theme](#changes-compared-to-the-original-theme) below. 23 24 ## Versioning 25 26 This theme used to be non-versioned, e.g. you'd pull the master branch, and occasionally new features or fixes would 27 be released. 28 29 Starting from version v1.0.0, the project adopted [Semantic Versioning](https://semver.org/). 30 31 Please check the [GitHub releases](https://github.com/pawroman/zola-theme-terminimal/releases) to see a change log 32 and work out if there's any breaking changes. 33 34 ## How to start 35 36 Option A: clone the theme directly into your Zola site folder: 37 38 ``` 39 $ git clone https://github.com/pawroman/zola-theme-terminimal.git themes/terminimal 40 ``` 41 42 Option B: include it as a git submodule (it's better if you plan to use CI builders): 43 44 ``` 45 $ git submodule add https://github.com/pawroman/zola-theme-terminimal.git themes/terminimal 46 ``` 47 48 Then in your `config.toml` set: 49 50 ```toml 51 theme = "terminimal" 52 53 # Sass compilation is required 54 compile_sass = true 55 ``` 56 57 Also see the Zola documentation on using themes: 58 https://www.getzola.org/documentation/themes/installing-and-using-themes/ 59 60 ## Shortcodes 61 62 The theme adds two custom shortcodes related to image handling. 63 64 ### `image` 65 66 Used to show images. 67 68 Required arguments: 69 70 - **`src`** 71 72 Optional arguments: 73 74 - **`alt`** 75 - **`position`** (center \[default\] | left | right) 76 - **`style`** 77 78 Example: 79 80 ``` 81 {{ image(src="/img/hello.png", alt="Hello Friend", 82 position="left", style="border-radius: 8px;") }} 83 ``` 84 85 ### `figure` 86 87 Same as `image`, but with a few extra optional arguments: 88 89 - **`caption`** 90 - **`caption_position`** (center \[default\] | left | right) 91 - **`caption_style`** 92 93 Example: 94 95 ``` 96 {{ figure(src="http://rustacean.net/assets/rustacean-flat-gesture.png", 97 style="width: 25%;", 98 position="right", 99 caption_position="left", 100 caption="Ferris, the (unofficial) Rust mascot", 101 caption_style="font-weight: bold; font-style: italic;") }} 102 ``` 103 104 ## Configuration 105 106 ### Colors 107 108 Both the accent colors and background colors are 109 configurable. 110 111 By default, both accent and background are set 112 to `blue`. 113 114 To configure menu, add this in `[extra]` section 115 of your `config.toml`: 116 117 ```toml 118 [extra] 119 120 # One of: blue, green, orange, pink, red. 121 # Defaults to blue. 122 # Append -light for light themes, e.g. blue-light 123 # Or append -auto, e.g. blue-auto 124 accent_color = "green" 125 126 # One of: blue, dark, green, orange, pink, red, light, auto 127 # Enabling dark background will also modify primary font color to be darker. 128 # Defaults to accent color (or, if not accent color specified, to blue). 129 background_color = "dark" 130 ``` 131 132 ### Logo text and link 133 134 You can set the "logo" text and what it links to, 135 by modifying `config.toml` like so: 136 137 ```toml 138 [extra] 139 140 # The logo text - defaults to "Terminimal theme" 141 logo_text = "My blog" 142 143 # The logo link - defaults to base_url. 144 logo_home_link = "/take/me/away!" 145 ``` 146 147 ### Author and copyright 148 149 You can set the footer's copyright author name like this: 150 151 ```toml 152 [extra] 153 154 # Author name: when specified, modifies the default 155 # copyright text. Apart from author, it will 156 # contain current year and a link to the theme. 157 author = "My Name" 158 ``` 159 160 If you don't like the default copyright text, 161 you can set it to completely custom HTML: 162 163 ```toml 164 [extra] 165 166 # Copyright text in HTML format. If specified, 167 # entirely replaces default copyright and author. 168 copyright_html = "My custom <b>copyright</b>" 169 ``` 170 171 ### Menu 172 173 The menu is optional, static (all items are always shown, 174 no matter what the screen size) and fully user-configurable. 175 176 To configure menu, add this in `[extra]` section 177 of your `config.toml`: 178 179 ```toml 180 [extra] 181 182 # menu is enabled by adding menu_items (optional) 183 menu_items = [ 184 # each of these is optional, name and url are required 185 # $BASE_URL is going to be substituted by base_url from configuration 186 {name = "blog", url = "$BASE_URL"}, 187 188 # tags should only be enabled if you have "tags" taxonomy 189 # see documentation below for more details 190 {name = "tags", url = "$BASE_URL/tags"}, 191 {name = "archive", url = "$BASE_URL/archive"}, 192 {name = "about me", url = "$BASE_URL/about"}, 193 194 # set newtab to true to make the link open in new tab 195 {name = "github", url = "url-to-your-github", newtab = true}, 196 ] 197 ``` 198 199 ### Tags 200 201 The theme optionally supports tags. To enable them, create 202 a "tags" taxonomy in your `config.toml`: 203 204 ```toml 205 taxonomies = [ 206 {name = "tags"}, 207 ] 208 ``` 209 210 Enabling tags will create a new `/tags` page, and 211 cause them to show up in `archive` section. Note 212 that you still need to create a menu link to the tags 213 page manually. 214 215 ### Pagination 216 217 Pagination is fully supported for post list (main site) 218 and intra-post (you can navigate to earlier and later posts). 219 220 To make sure pagination works properly, you must first configure 221 it in `content/_index.md`: 222 223 ``` 224 +++ 225 # number of pages to paginate by 226 paginate_by = 2 227 228 # sorting order for pagination 229 sort_by = "date" 230 +++ 231 ``` 232 233 Then, tweak the theme's pagination config in `config.toml`: 234 235 ```toml 236 [extra] 237 238 # Whether to show links to earlier and later posts 239 # on each post page (defaults to true). 240 enable_post_view_navigation = true 241 242 # The text shown at the bottom of a post, 243 # before earlier/later post links. 244 # Defaults to "Thanks for reading! Read other posts?" 245 post_view_navigation_prompt = "Read more" 246 ``` 247 248 ### Language code 249 250 Internationalization / translation is not supported 251 but you can set the HTML language code for your 252 site: 253 254 ```toml 255 default_language = "en" 256 ``` 257 258 ### Hack font subset 259 260 By default, the theme uses a mixed subset of the Hack font. 261 Normal weight font uses full character set 262 (for Unicode icons and special symbols), but all others 263 (bold, italic etc) use a limited subset. 264 265 This results in much smaller transfer sizes, but the subset 266 might not contain all the Unicode characters you need. 267 268 You can enable full unicode support in `config.toml`: 269 270 ```toml 271 [extra] 272 273 # Use full Hack character set, not just a subset. 274 # Switch this to true if you need full unicode support. 275 # Defaults to false. 276 use_full_hack_font = true 277 ``` 278 279 Also see [Hack's docs](https://github.com/source-foundry/Hack/blob/master/docs/WEBFONT_USAGE.md). 280 281 ### Favicon 282 283 The theme supports adding a global favicon (applies to 284 all pages) to the site: 285 286 ```toml 287 # Optional: Global favicon URL and mimetype. 288 # Mimetype defaults to "image/x-icon". 289 # The URL should point at a file located 290 # in your site's "static" directory. 291 favicon = "/favicon.png" 292 favicon_mimetype = "image/png" 293 ``` 294 295 ### Page titles 296 297 The theme allows you to configure how the page titles (the `<title>` elements) are rendered. 298 299 Use `"combined"` to render titles as `"Page title | Main title"`. 300 301 ```toml 302 # Optional: Set how <title> elements are rendered. 303 # Values: 304 # - "main_only" -- only the main title (`config.title`) is rendered. 305 # - "page_only" -- only the page title (if defined) is rendered, 306 # falling back to `config.title` if not defined or empty. 307 # - "combined" -- combine like so: "page_title | main_title", 308 # or if page_title is not defined or empty, fall back to `main_title` 309 # 310 # Note that the main (index) page only has the main title. 311 page_titles = "combined" 312 ``` 313 314 All the configuration options are also described in 315 [`config.toml`](../master/config.toml). 316 317 ## Extending 318 319 Each of the templates defines named blocks, so 320 it should be quite easy to customize the most common things. 321 322 For example, if you want to add extra `<meta>` tags to the 323 base template, `index.html`, create file like this in `templates/index.html`: 324 325 ```html 326 {% extends "terminimal/templates/index.html" %} 327 328 {% block extra_head %} 329 <meta name="description" content="My awesome website"/> 330 <meta name="keywords" content="Hacking,Programming,Ranting"/> 331 {% endblock %} 332 ``` 333 334 ## How to contribute 335 336 If you spot any bugs or wish to contribute new features, please create a new 337 [Pull Request](https://github.com/pawroman/zola-theme-terminimal/pulls). 338 339 ## Changes compared to the original theme 340 341 This theme has been forked from https://github.com/panr/hugo-theme-terminal 342 343 - Slight changes in the layout and styling. 344 - Content has been centered (instead of left-aligned). 345 - The header stripes have been spaced out. 346 - Tweaks to pagination, especially on mobile (small screens). 347 - The post title underline is dashed instead of doubly-dotted. 348 - All links are underlined, as per 349 [Brutalist Web Design Guidelines](https://www.brutalist-web.design/). 350 - Tweaks to header font sizes. 351 - Minor footer tweaks. 352 353 - Absolutely **no JavaScript**. 354 - No JavaScript needed to pre-process anything. 355 Zola with its Sass pre-processor is the only dependency. 356 - There's no menu trigger. 357 - Things load crazy fast, as it's all static content. 358 - Prism.js syntax highlighting is not supported (you can use 359 [Zola's](https://www.getzola.org/documentation/content/syntax-highlighting/)). 360 361 - All references to social media (e.g. Twitter, OpenGraph) have been removed. 362 363 - All references to external URLs (e.g. Google CDN) have been removed. 364 This theme's static assets are meant to be served from where it's hosted. 365 366 - [Hack](https://github.com/source-foundry/Hack) is the default font. 367 368 - The default color theme is blue (original uses orange). 369 370 ### New features 371 372 - You can pick the accent color as well as background color. 373 There's a new `dark` background. See [Configuration](#configuration) 374 below for details. 375 - Active "section" links will change color indicating the 376 active section. This is all static, done at template level. 377 378 ### Features retained from the original 379 380 - 5 color themes, depending on your preference: 381 blue (default), green, orange, pink, red. 382 - The shortcodes `image` and `figure` (See [Shortcodes](#shortcodes)). 383 - Fully responsive. 384 385 ## License 386 387 Copyright © 2019 Paweł Romanowski (pawroman) 388 389 Original theme: Copyright © 2019 Radosław Kozieł ([@panr](https://twitter.com/panr)) 390 391 The theme is released under the MIT License. 392 Check the [license file](../master/LICENSE.md) 393 for more information. 394 395 The license for Hack fonts used is included in 396 [LICENSE-Hack.md](../master/LICENSE-Hack.md).