├── .gitignore ├── LICENSE.md ├── README.md ├── archetypes └── post.md ├── exampleSite ├── .gitignore ├── archetypes │ └── default.md ├── config.toml └── content │ ├── page │ └── about.md │ └── post │ ├── goisforlovers.md │ ├── hugoisforlovers.md │ ├── migrate-from-jekyll.md │ └── shortcodes │ ├── 01.jpg │ └── index.md ├── images ├── classicindex.png ├── classicindex_tn.png ├── codecaption1.png ├── compactindex.png ├── compactindex_tn.png ├── screenshot.png └── tn.png ├── layouts ├── 404.html ├── _default │ ├── _markup │ │ └── render-link.html │ ├── list.html │ └── single.html ├── index.html ├── license │ └── single.html ├── page │ └── single.html ├── partials │ ├── classic_index.html │ ├── compact_index.html │ ├── custom_twitter_card.html │ ├── extend_footer.html │ ├── extend_header.html │ ├── footer.html │ ├── header.html │ ├── navigation.html │ ├── octo_header.html │ ├── pagination.html │ ├── post_footer.html │ ├── post_header.html │ ├── sidebar.html │ └── social.html └── shortcodes │ ├── codecaption.html │ ├── imgcap.html │ └── toc.html ├── sample-config.toml ├── static ├── css │ ├── fonts.css │ ├── fork-awesome.min.css │ └── hugo-octopress.css ├── favicon.png └── fonts │ ├── forkawesome-webfont.eot │ ├── forkawesome-webfont.svg │ ├── forkawesome-webfont.ttf │ ├── forkawesome-webfont.woff │ ├── forkawesome-webfont.woff2 │ ├── pt-sans-v9-latin-700.woff │ ├── pt-sans-v9-latin-700.woff2 │ ├── pt-sans-v9-latin-700italic.woff │ ├── pt-sans-v9-latin-700italic.woff2 │ ├── pt-sans-v9-latin-italic.woff │ ├── pt-sans-v9-latin-italic.woff2 │ ├── pt-sans-v9-latin-regular.woff │ ├── pt-sans-v9-latin-regular.woff2 │ ├── pt-serif-v9-latin-700.woff │ ├── pt-serif-v9-latin-700.woff2 │ ├── pt-serif-v9-latin-700italic.woff │ ├── pt-serif-v9-latin-700italic.woff2 │ ├── pt-serif-v9-latin-italic.woff │ ├── pt-serif-v9-latin-italic.woff2 │ ├── pt-serif-v9-latin-regular.woff │ └── pt-serif-v9-latin-regular.woff2 └── theme.toml /.gitignore: -------------------------------------------------------------------------------- 1 | Thumbs.db 2 | thumbs.db 3 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2018 Parsia Hakimian 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the "Software"), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software is furnished to do so, 10 | subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Hugo-Octopress 2 | Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to 3 | [Hugo][hugo-link]. 4 | 5 | Live demo using the unmodified theme: 6 | 7 | * [http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/][live-demo]. 8 | * Source: [https://github.com/parsiya/Hugo-Octopress-Test][test-repo]. 9 | 10 | [live-demo]: http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/ 11 | [test-repo]: https://github.com/parsiya/Hugo-Octopress-Test 12 | 13 | My personal website with the compact index (see below): 14 | 15 | * [https://parsiya.net](https://parsiya.net). 16 | * Source: [https://github.com/parsiya/parsiya.net](https://github.com/parsiya/parsiya.net) 17 | 18 | ## Contents 19 | - [Quick start](#quick-start) 20 | - [Configuration](#configuration) 21 | - [Code highlight](#code-highlight) 22 | - [Goldmark vs. Blackfriday Markdown Engines](#goldmark-vs-blackfriday-markdown-engines) 23 | - [CSS override](#css-override) 24 | - [Navigation menu](#navigation-menu) 25 | - [Extending Headers and Footers](#extending-headers-and-footers) 26 | - [Sidebar](#sidebar) 27 | - [Sidebar text](#sidebar-text) 28 | - [Social network icons](#social-network-icons) 29 | - [Sidebar menu](#sidebar-menu) 30 | - [Recent posts](#recent-posts) 31 | - [Shortcodes](#shortcodes) 32 | - [Code caption](#code-caption) 33 | - [Image caption](#image-caption) 34 | - [Table of Contents](#table-of-contents) 35 | - [Pages](#pages) 36 | - [License page](#license-page) 37 | - [Not Found or 404.html](#not-found-or-404html) 38 | - [Taxonomy pages](#taxonomy-pages) 39 | - [Individual pages](#individual-pages) 40 | - [Table of contents](#table-of-contents-1) 41 | - [toc configuration](#toc-configuration) 42 | - [Use toc in Frontmatter](#use-toc-in-frontmatter) 43 | - [Use the toc Shortcode](#use-the-toc-shortcode) 44 | - [Editor Plugins](#editor-plugins) 45 | - [Disqus](#disqus) 46 | - [Twitter Card](#twitter-card) 47 | - [Compact Index](#compact-index) 48 | - [mainSections](#mainsections) 49 | - [Custom favicon](#custom-favicon) 50 | - [Troubleshooting](#troubleshooting) 51 | - [Hugo page summary bug](#hugo-page-summary-bug) 52 | - [Empty Posts Link on Homepage](#empty-posts-link-on-homepage) 53 | - [Issues/TODO](#issuestodo) 54 | - [Attribution](#attribution) 55 | - [Ported by](#ported-by) 56 | - [Theme license](#theme-license) 57 | 58 | ![screenshot](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/screenshot.png) 59 | 60 | ## Quick start 61 | Add the theme to your existing site or [Hugo's quick start][hugo-quickstart]. 62 | All commands are run from the root directory of your website. 63 | 64 | [hugo-quickstart]: https://gohugo.io/getting-started/quick-start/ 65 | 66 | If using git to manage your website, add the theme as a git submodule: 67 | 68 | ``` 69 | git submodule add https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress 70 | ``` 71 | 72 | Or you can clone it: 73 | 74 | ``` 75 | git clone https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress 76 | ``` 77 | 78 | To view the theme with the example site: 79 | 80 | ``` 81 | cd themes/Hugo-Octopress/ 82 | hugo serve -vw --source=exampleSite 83 | ``` 84 | 85 | And view the example website at http://localhost:1313. 86 | 87 | Example site was originally created by 88 | [https://github.com/nonumeros][nonumeros]. I reviewed the 89 | [pull request][examplesite-pr] almost two years late and had to copy/paste the 90 | website instead of resolving merge conflicts. The example website also has a 91 | page with the theme's shortcodes. 92 | 93 | [nonumeros]: https://github.com/nonumeros 94 | [examplesite-pr]: https://github.com/parsiya/Hugo-Octopress/pull/57 95 | 96 | ## Configuration 97 | Hugo-Octopress can be configured by modifying the parameters in the 98 | [configuration file](https://gohugo.io/overview/configuration/). 99 | [sample-config.toml](sample-config.toml) and 100 | [exampleSite/config.toml](exampleSite/config.toml) are both working examples. 101 | 102 | ## Code highlight 103 | This theme uses the built-in [Chroma][chroma-link] highlighter with the 104 | `solarized-dark` theme. See all supported styles at 105 | [https://xyproto.github.io/splash/docs/all.html](https://xyproto.github.io/splash/docs/all.html). 106 | To change the style, change it in the config file like below to one of the 107 | supported styles. 108 | 109 | [chroma-link]: https://github.com/alecthomas/chroma 110 | 111 | Some options to control code highlighting post version `0.60`. 112 | 113 | ``` toml 114 | [markup] 115 | [markup.tableOfContents] 116 | endLevel = 8 117 | startLevel = 1 118 | [markup.highlight] 119 | style = "solarized-dark" 120 | ``` 121 | 122 | For more configuration options please see 123 | [https://gohugo.io/getting-started/configuration-markup/#highlight][hugo-configuration-markup] 124 | and [https://gohugo.io/extras/highlighting/][hugo-syntax-highlighting] in Hugo's 125 | documentation. 126 | 127 | [hugo-syntax-highlighting]: https://gohugo.io/extras/highlighting/ 128 | [hugo-configuration-markup]: https://gohugo.io/getting-started/configuration-markup/#highlight 129 | 130 | ## Goldmark vs. Blackfriday Markdown Engines 131 | Prior to version `0.60`, Hugo used Blackfriday. Now it uses Goldmark by default. 132 | See https://gohugo.io/getting-started/configuration-markup#highlight for 133 | information about setting it up. 134 | 135 | There are trade-offs. Mainly, the `hrefTargetBlank` Blackfriday extension. It 136 | was set to true to open external links in a new browser tab. Unfortunately, 137 | Goldmark does not have this built-in. To make it happen, we need to use a render 138 | hook. I used the one in Hugo docs at 139 | 140 | https://gohugo.io/getting-started/configuration-markup#link-with-title-markdown-example. 141 | 142 | This works for markdown links but not linkify or image links. Linkify links are 143 | straight URLs pasted into the document (e.g., `https://example.net`). A 144 | workaround is not having links similar to this (which is not in the markdown 145 | standard anyways) and use normal links. For example, 146 | `[example.net](https://example.net)` or reference links. 147 | 148 | You can keep using Blackfriday like this: 149 | 150 | ``` toml 151 | [markup] 152 | defaultMarkdownHandler = "blackfriday" 153 | [markup.blackFriday] 154 | hrefTargetBlank = true 155 | ``` 156 | 157 | ## CSS override 158 | You can override the built-in CSS and add your own. Put your CSS files in the 159 | `static` directory of your website. While storing them inside the 160 | `themes/Hugo-Octopress/static` directory works, it's not recommended (keep your 161 | website and theme as separated as possible to be able to switch themes easily). 162 | Then modify the `customCSS` parameter. The path should be relative to the 163 | `static` folder. These CSS files will be added through the `header` partial 164 | after the built-in CSS file. 165 | 166 | For example, if custom CSS files are `static/css/custom.css` and 167 | `static/css/custom2.css` then `customCSS` will look like this: 168 | 169 | ``` toml 170 | [params] 171 | customCSS = ["css/custom.css","css/custom2.css"] 172 | ``` 173 | 174 | ## Navigation menu 175 | Links in the navigation menu (everything other than Google search and RSS icon) 176 | can be customized. The navigation menu is generated using the 177 | `layouts/partials/navigation.html` partial. 178 | 179 | By default, navigation menu links will open in the same window. You can change 180 | this behavior by setting the `navigationNewWindow` parameter to true. Links to 181 | root ("/") will always open in the same window. Currently, Hugo does not support 182 | adding custom attributes to menus. 183 | 184 | Links are sorted according to weight from left to right. For example, a link 185 | with weight of `-10` will appear to the left of links with weights `0` or `10`. 186 | Links can be added to the config file: 187 | 188 | ``` toml 189 | [[menu.main]] 190 | Name = "Blog" 191 | URL = "/" 192 | weight = -10 193 | 194 | [[menu.main]] 195 | Name = "The other guy from Wham!" 196 | URL = "https://www.google.com/search?q=andrew+ridgeley" 197 | weight = -5 198 | 199 | [[menu.main]] 200 | Name = "This theme - add link" 201 | URL = "https://www.github.com" 202 | 203 | [params] 204 | # If set to true, navigation menu links will open in a new window with the exception of links to root ("/") 205 | # If this item does not exist or is set to false, then navigation menu links will open in the same window 206 | navigationNewWindow = true 207 | ``` 208 | 209 | Search engine customization: 210 | 211 | ``` toml 212 | [params] 213 | searchEngineURL = "https://www.google.com/search" 214 | ``` 215 | 216 | ## Extending Headers and Footers 217 | Copy these files from `theme/Hugo-Octopress/layouts/partials/` into 218 | `your-site/layouts/partials` and modify them: 219 | 220 | * `extend_header.html`: Everything will be added to the end of the `head` tag on 221 | every page. 222 | * `extend_footer.html`: Everything will be added after the `footer` tag on every 223 | page. 224 | 225 | ## Sidebar 226 | The sidebar has four sections, from top to bottom: 227 | 228 | * Sidebar header and text (optional). 229 | * Social network icons (optional): Icons and links to GitHub, Mastodon, and more. 230 | * Sidebar menu (optional): Links in sidebar. 231 | * Recent posts: Displays last X posts (default is 5). 232 | 233 | The sidebar is generated using the partial at `layouts/partials/sidebar.html`. 234 | 235 | ### Sidebar text 236 | The sidebar text has two parts and both can be configured. Both are passed to 237 | `markdownify` so you can use markdown (e.g. add links or new lines). 238 | 239 | * Sidebar header appears first in an `

` tag. It can be configured with 240 | `sidebarHeader`. 241 | * Sidebar text appears under the header and is in `sidebarText`. 242 | 243 | You can add new lines can be added with two spaces at the end of line. New 244 | paragraphs can be added with two an empty line. when adding two new lines, 245 | remember to remove the indentation otherwise the new line will be treated as a 246 | codeblock. 247 | 248 | ``` toml 249 | sidebarHeader = "Sidebar Header" 250 | 251 | sidebarText = """Here's a [link to google](https://www.google.com) 252 | 253 | New paragraph 254 | 255 | Another paragraph which has two spaces in the end to create a new line using markdown 256 | New line but not a new paragraph 257 | """ 258 | ``` 259 | 260 | If you want to use `
` here and not just markdown, you need to enable unsafe 261 | rendering of HTML in Goldmark. You can do this like this. 262 | 263 | ``` toml 264 | [markup] 265 | [markup.goldmark] 266 | [markup.goldmark.renderer] 267 | unsafe = true 268 | ``` 269 | 270 | Blackfriday renders the `
` tags and does not need extra configuration. 271 | 272 | ### Social network icons 273 | Sidebar social network icons are configured as follows: 274 | 275 | ``` toml 276 | [params] 277 | github = "https://github.com/parsiya/Hugo-Octopress/" 278 | bitbucket = "" 279 | gitlab = "" 280 | twitter = "" 281 | keybase = "" 282 | linkedin = "" 283 | mastodon = "" 284 | stackoverflow = "" 285 | youtube = "" 286 | facebook = "" 287 | instagram = "" 288 | bitcoin = "" 289 | ``` 290 | 291 | Icon sequence is unfortunately hardcoded. To modify, copy 292 | `your-website/themes/Hugo-Octopress/layouts/partials/social.html` to 293 | `your-website/layouts/partials/social.html` and modify the sequence. Use `
` 294 | to create a new line. 295 | 296 | Code to display links (and the idea to use these icons) is from 297 | [Hyde-x][hyde-x-theme]. 298 | 299 | [hyde-x-theme]: https://github.com/zyro/hyde-x/ 300 | 301 | Icons are from [Font Awesome][font-awesome] and [Fork Awesome][fork-awesome]. To 302 | use icons with square dark backgrounds add `-square`. For example, 303 | ``. Size can be from 1 to 5 use 304 | `fa-lg` to make them adaptive. 305 | 306 | [font-awesome]: https://fontawesome.com/ 307 | [fork-awesome]: https://github.com/ForkAwesome/Fork-Awesome 308 | 309 | ### Sidebar menu 310 | This menu can be enabled by setting `sidebarMenuEnabled` to `true`. It has two 311 | sections: 312 | 313 | * A header that appears inside the `

` tag on top. It can be set by 314 | `sidebarMenuHeader`. This part only supports text. 315 | * A set of links. They can be configured similar to the navigation menu items by 316 | using the `[[menu.sidebar]]` tag. Set `sidebarNewWindow` to `true` to open 317 | these links in a new window 318 | 319 | ``` toml 320 | [[menu.sidebar]] 321 | Name = "Google" 322 | URL = "https://www.google.com" 323 | weight = 0 324 | 325 | [[menu.sidebar]] 326 | Name = "Hugo" 327 | URL = "/categories/hugo/" 328 | weight = 1 329 | ``` 330 | 331 | ### Recent posts 332 | Last x posts can be displayed in the sidebar. This number is controlled by 333 | `sidebarRecentLimit`. To hide this section you can remove `sidebarRecentLimit` 334 | from the config file or set it to zero. 335 | 336 | ## Shortcodes 337 | Creating [shortcodes][hugo-shortcodes] in Hugo is very easy and one of the 338 | reasons I switched to it. I recreated a few plugins from Octopress. They add 339 | captions to code blocks and images. These shortcodes are in 340 | `layouts/shortcodes/`. 341 | 342 | For all my Hugo shortcodes see 343 | [https://github.com/parsiya/Hugo-Shortcodes][my-shortcodes]. 344 | 345 | [hugo-shortcodes]: https://gohugo.io/extras/shortcodes 346 | [my-shortcodes]: https://github.com/parsiya/Hugo-Shortcode 347 | 348 | ### Code caption 349 | This shortcode adds a caption to codeblocks. The codeblock is wrapped in a 350 | `
` tag and caption is added using `
`. It has two parameters, 351 | `title` which is the caption of the code block and `lang` which is the language 352 | that is passed to the Hugo's `highlight` function along with `linenos=true` to 353 | enable line numbers. 354 | 355 | Usage and source (parameters are named and not positional): 356 | 357 | ``` html 358 | {{< codecaption lang="html" title="Code caption shortcode" >}} 359 |
360 |
361 | {{ .Get "title" }} 362 |
363 |
364 | {{ highlight .Inner (.Get "lang") "linenos=true" }} 365 |
366 |
367 | {{< /codecaption >}} 368 | ``` 369 | 370 | And will look like: 371 | 372 | ![picture](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/codecaption1.png). 373 | 374 | If the code inside the tag overflows, a horizontal sidebar will be added to the 375 | table. It took me a while to achieve this as the `highlight` function created 376 | tables that were out of my control. The output from `highlight` is wrapped in 377 | `
` and the scroll bar will be added for the whole 378 | `div`. The following in the CSS file (starting from line 2225) enables this 379 | behavior: 380 | 381 | ``` css 382 | div.codewrapper { 383 | overflow-x: auto; 384 | overflow-y: hidden; 385 | background-color: #002B36; 386 | } 387 | ``` 388 | 389 | ### Image caption 390 | This shortcode adds captions to pictures. Due to the way the original CSS file 391 | was organized, this shortcode does not use `
` and `
`. `Alt` 392 | tag is also set to `title`. 393 | 394 | Usage (parameters are named and not positional): 395 | 396 | ``` go 397 | {{< imgcap title="Sample caption" src="/images/2016/thetheme/1.png" >}} 398 | ``` 399 | 400 | Results in: 401 | 402 | ``` html 403 | 404 | Sample caption 405 | Sample caption 406 | 407 | ``` 408 | 409 | ### Table of Contents 410 | This shortcode adds table of contents to the theme. You can use it to add the 411 | toc to anywhere in the page with `{{< toc >}}`. 412 | 413 | ## Pages 414 | This section discusses the different kind of pages that are supported by the 415 | theme. 416 | 417 | ### License page 418 | License page address is `baseurl/license/`. Create a markdown file containing 419 | the text for the license page under `content` and set its type to `license` in 420 | frontmatter: 421 | 422 | ``` yaml 423 | --- 424 | title: "License" 425 | type: license 426 | --- 427 | 428 | License text 429 | ``` 430 | 431 | License page template is: `layouts/license/single.html`. 432 | 433 | ### Not Found or 404.html 434 | The `404.html` page has two optional parameters and both support markdown: 435 | 436 | * `notFoundHeader`: 404 page title 437 | * `notFoundText`: 404 page text 438 | 439 | If they are not set in the config file, theme's default page is used 440 | (`layouts/404.html`). 441 | 442 | ### Taxonomy pages 443 | You can create taxonomy lists (e.g. categories and tags). Set 444 | `generateTaxonomyList = true` to get generate them at `baseURL/tags/` and 445 | `baseURL/categories`. By default items are sorted by count. 446 | `sortTaxonomyAlphabetical = true` changes the sort to alphabetical. 447 | 448 | ``` toml 449 | [Params] 450 | generateTaxonomyList = true 451 | 452 | # Alphabetical sort 453 | # sortTaxonomyAlphabetical = true 454 | ``` 455 | 456 | To revert, remove `sortTaxonomyAlphabetical` or set it to false. 457 | 458 | Note: As of Hugo 0.33, `indexes` has been removed. If your taxonomy pages are 459 | not rendered, please update to the latest version of Hugo. Templates are now at: 460 | 461 | * `/layouts/category/category.html` 462 | * `/layouts/tag/tag.html` 463 | 464 | ### Individual pages 465 | You can create individual pages in at least two ways: 466 | 467 | * Create a new content file in `content/page`. 468 | * Create a page anywhere inside `content` and set the type to `page` in 469 | frontmatter. E.g. `type: page`. 470 | 471 | The template for individual pages is at 472 | `Hugo-Octopress/layouts/page/single.html`. It can be overridden by a file in the 473 | website's `layouts/page/single.html`. For more information see 474 | [Single Page Templates in Hugodocs][hugo-single-page-templates]. 475 | 476 | [hugo-single-page-templates]: https://gohugo.io/templates/single-page-templates/ 477 | 478 | ## Table of contents 479 | There are three ways to add `Table of Contents (ToC)` to pages. 480 | 481 | ### toc configuration 482 | With Goldmark, you need to change the defaults for the table of contents 483 | renderer in your site's config. The defaults only render markdown headings level 484 | 2 and 3. 485 | 486 | ``` toml 487 | [markup] 488 | [markup.tableOfContents] 489 | endLevel = 8 490 | startLevel = 1 491 | ``` 492 | 493 | Please see more at 494 | [https://gohugo.io/getting-started/configuration-markup/#table-of-contents][toc-config]. 495 | 496 | [toc-config]: https://gohugo.io/getting-started/configuration-markup/#table-of-contents 497 | 498 | ### Use toc in Frontmatter 499 | This ToC is on top of the page and does not appear in the summary. You can 500 | customize the ToC for each page or globally: 501 | 502 | 1. Add a variable named `toc` to the frontmatter of the post/page and set it to `true`. 503 | 504 | ``` yaml 505 | title: "title" 506 | date: 2016-04-01T20:22:37-04:00 507 | draft: false 508 | toc: true 509 | ``` 510 | 511 | 2. Enable it globally by setting `tableOfContents` under `[Params]` to `true`. 512 | 513 | ``` toml 514 | [Params] 515 | tableOfContents = true 516 | ``` 517 | 518 | The `toc` variable in the frontmatter has priority. If it is set to `false` the 519 | global setting is ignored for that page. 520 | 521 | ### Use the toc Shortcode 522 | If you want the table to appear in a different location use the shortcode. For 523 | example, in [the cheatsheet on my website][website-cheatsheet] it appears after 524 | the summary. 525 | 526 | ``` 527 | --- 528 | frontmatter 529 | --- 530 | 531 | summary or whatever. 532 | 533 | {{< toc >}} 534 | ``` 535 | 536 | [website-cheatsheet]: https://raw.githubusercontent.com/parsiya/parsiya.net/master/content/page/CheatSheet.markdown 537 | 538 | ### Editor Plugins 539 | There are various editor plugins that create a table of contents in markdown 540 | using markdown links. This approach is self-contained and not reliant on the 541 | theme or the shortcode. I used the VS Code plugins 542 | [Markdown All in One][markdown-vscode-toc]. 543 | 544 | [markdown-vscode-toc]: https://github.com/yzhang-gh/vscode-markdown#table-of-contents 545 | 546 | ## Disqus 547 | Hugo supports Disqus. Note Disqus shortname is directly in the config file. As 548 | of at least v0.134.0, the location has changed and this old one will be 549 | deprecated in a bit. For now, (before v0.135.0), the theme still supports this 550 | location, but you should switch it if you want to keep using the latest Hugo 551 | versions. 552 | 553 | Reference: https://gohugo.io/content-management/comments/#configure-disqus. 554 | 555 | ``` toml 556 | # new location 557 | # [services] 558 | # [services.disqus] 559 | # shortname = "Your disqus shortname" 560 | 561 | # old one. 562 | disqusShortname = "whatever" 563 | ``` 564 | 565 | You can disable comments for individual pages by adding `comments: false` to 566 | the frontmatter. 567 | 568 | ## Twitter Card 569 | Twitter card support can be enabled in the config file under `Params`: 570 | 571 | ``` toml 572 | [params] 573 | # Twitter card config 574 | # Enable. 575 | twitterCardEnabled = true 576 | # Don't include the @. 577 | # twitterCardSite = 578 | twitterCardDomain = "parsiya.net" 579 | # Don't include the @. 580 | twitterCardAuthor = "CryptoGangsta" 581 | ``` 582 | 583 | After Twitter card is enabled, you can add summary images to your posts in front 584 | matter with `twitterImage`: 585 | 586 | ``` yaml 587 | twitterImage: 02-fuzzer-crash.png 588 | ``` 589 | 590 | **Note:** Image URL should be relative to the page, otherwise the final URL will 591 | not be correct. In short, image URL should be part of the page bundle. In this 592 | case, both `index.md` and `02-fuzzer-crash.png` are in the same root directory. 593 | If the image is in a subdirectory of page bundle, it can be added like this: 594 | 595 | ``` yaml 596 | twitterImage: images/02-fuzzer-crash.png 597 | ``` 598 | 599 | To modify this template, copy 600 | `your-website/themes/Hugo-Octopress/layouts/partials/custom_twitter_card.html` 601 | to `your-website/layouts/partials/custom-twitter-card.html` and make changes. 602 | 603 | ## Compact Index 604 | The original theme renders each post's summary in the main page. I prefer a more 605 | compact index and use it for my own website. You can enable it by adding this to 606 | the config file: 607 | 608 | ``` toml 609 | [params] 610 | # Set to true to enable compact index. Set to false or remove to go back to classic view. 611 | compactIndex = true 612 | ``` 613 | 614 | Compare the views (classic - compact) - click for full-size image: 615 | 616 | [![classic index](images/classicindex_tn.png)](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/classicindex.png) [![compact index](images/compactindex_tn.png)](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/compactindex.png) 617 | 618 | ## mainSections 619 | Hugo-Octopress supports using the [mainSections][hugo-mainsections] property in 620 | the config file to display different kinds of posts on the main page. If not 621 | defined, `mainSection` will default to the section with the most number of 622 | pages. In a vanilla Hugo-Octopress setup, it will be under `post`. But, you can 623 | add your own sections in the config file: 624 | 625 | ```toml 626 | [params] 627 | mainSections = ["posts", "blogs"] 628 | ``` 629 | 630 | [hugo-mainsections]: https://gohugo.io/functions/where/#mainsections 631 | 632 | See the code in `layouts/partials/classic_index.html`: 633 | 634 | ```html 635 |
636 | {{ $paginator := where site.RegularPages "Type" "in" site.Params.mainSections | .Paginate }} 637 | {{ range $paginator.Pages }} 638 |
639 | ... 640 | ``` 641 | 642 | ## Custom Favicon 643 | The theme uses the [default Octopress favicon](static/favicon.png). You can 644 | modify it: 645 | 646 | 1. Add `favicon` to the config file under `params`. This path is relative to the 647 | `static` directory. 648 | ```toml 649 | [params] 650 | favicon = "myicon.png" 651 | ``` 652 | 2. Store the file in **your site's** static directory: 653 | `your-site/static/myicon.png`. 654 | 655 | # Troubleshooting 656 | Common issues when dealing with the theme. 657 | 658 | ## Hugo page summary bug 659 | Without a summary divider ``, Hugo uses the first 70 words of the 660 | post. The result is usually not pretty and contains raw HTML. Always use the 661 | summary divider `` in your posts. This does not matter if you 662 | use the compact index because it does not use the summary. 663 | 664 | Hugo does not display render style links in the page summary if the link is also 665 | not before the summary divider. You can read more 666 | [here](https://discuss.gohugo.io/t/markdown-content-renders-as-regular-text-in-summary/1396/12). 667 | 668 | Reference style links look like this: 669 | 670 | ``` markdown 671 | This is a link to [Example][example-link]. 672 | 673 | [example-link]: https://www.example.com 674 | ``` 675 | 676 | There are two workarounds: 677 | 678 | 1. Do not use reference style links in summary. Use normal links like `[Example](https://www.example.com)`. 679 | 2. Put the reference links before the summary divider. 680 | 681 | ### Empty Posts Link on Homepage 682 | After rebuilding the blog with Hugo `0.57`, you may see a single `Posts` link in 683 | the classic index. Update to Hugo `0.57.2+` (there is an issue with `0.57.1`) 684 | and it should work. 685 | 686 | For more information please see: 687 | 688 | * https://github.com/gohugoio/hugoThemes/issues/682 689 | 690 | This should not be an issue anymore because the theme's minimum version of Hugo 691 | has been bumped. 692 | 693 | ## Issues/TODO 694 | If you discover any issues/bugs or want new features please use the GitHub issue 695 | tracker. Please keep in my mind that development has not been my day job for 696 | quite a while and I may be slow in fixing things (don't be surprised if I ask 697 | you about details). 698 | 699 | **The css is a mess.** The CSS file is taken directly from the classic Octopress 700 | theme. I found it easier to just modify the templates to generate HTML code 701 | similar to Octopress' output and use the existing CSS file. It's bulky (around 702 | 53KBs and 2300 lines) and it probably has code for elements that are never used 703 | (also duplicates). 704 | 705 | ## Attribution 706 | * [Octopress][octopress-link] is created by [Brandon Mathis][mathis-link]. 707 | Octopress source can be found on 708 | [https://github.com/imathis/octopress][octopress-github]. 709 | * Some code was taken from the [Hyde-x][hyde-x-theme] Hugo theme by [Andrei Mihu][andrei-mihu-link]. 710 | * Sidebar icons are from [Font Awesome][font-awesome] by Dave Gandy and [Fork Awesome][fork-awesome]. 711 | * Special thanks to [contributors][theme-contributors] and everyone who has 712 | helped with issues. 713 | 714 | [octopress-github]: https://github.com/octopress/octopress 715 | [mathis-link]: https://github.com/imathis 716 | [theme-contributors]: https://github.com/parsiya/Hugo-Octopress/graphs/contributors 717 | [andrei-mihu-link]: http://andreimihu.com/ 718 | 719 | ## Ported by 720 | Ported by [Parsia](https://parsiya.net). 721 | 722 | ## Theme license 723 | Open sourced under the [MIT license](LICENSE.md). 724 | 725 | 726 | [octopress-link]: http://octopress.org 727 | [hugo-link]: https://gohugo.io 728 | -------------------------------------------------------------------------------- /archetypes/post.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "{{ replace .TranslationBaseName "-" " " | title }}" 3 | date: {{ .Date }} 4 | draft: true 5 | toc: false 6 | comments: false 7 | categories: 8 | - category1 9 | - category2 10 | tags: 11 | - tag1 12 | - tag2 13 | --- 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /exampleSite/.gitignore: -------------------------------------------------------------------------------- 1 | resources 2 | .hugo_build.lock -------------------------------------------------------------------------------- /exampleSite/archetypes/default.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "{{ replace .Name "-" " " | title }}" 3 | date: {{ .Date }} 4 | draft: true 5 | --- 6 | 7 | -------------------------------------------------------------------------------- /exampleSite/config.toml: -------------------------------------------------------------------------------- 1 | 2 | baseurl = "https://example.com" 3 | disablePathToLower = false 4 | languageCode = "en-us" 5 | title = "Site title" 6 | theme = "Hugo-Octopress" 7 | 8 | # Needed so we can serve the example website without extra switches 9 | themesDir = "../.." 10 | 11 | # Disqus shortcode 12 | # Disable comments for any individual post by adding "comments: false" in its frontmatter 13 | # Note it's not under [params] anymore 14 | # disqusShortname = "Your disqus shortname" 15 | 16 | # Number of blog posts in each pagination page 17 | paginate = 6 18 | 19 | [permalinks] 20 | post = "/blog/:year-:month-:day-:title/" # change the post URL to look like the old ones 21 | 22 | [params] 23 | 24 | # --- Start sidebar options --- 25 | # Number of last posts that will be displayed in the sidebar - set to 0 or remove to hide this section 26 | sidebarRecentLimit = 5 27 | 28 | # Sidebar header - passed to markdownify so you can write markdown here 29 | sidebarHeader = "Sidebar Header" 30 | 31 | # Sidebar text also supports markdown 32 | # New lines can be added with two spaces at the end of line. New paragraphs can be added with two an empty line. 33 | # when adding two new lines, remember to remove the indentation otherwise the new line will be treated as a codeblock 34 | sidebarText = """Here's a [link to example.net](https://www.example.net) 35 | 36 | New paragraph 37 | 38 | Another paragraph which has two spaces in the end to create a new line using markdown 39 | New line but not a new paragraph 40 | """ 41 | # Sidebar menu - if true will add a sidebar menu between sidebar text and recent posts 42 | sidebarMenuEnabled = true 43 | sidebarMenuHeader = "Sidebar Links" 44 | 45 | # sidebar links 46 | github = "https://github.com/parsiya/Hugo-Octopress" 47 | bitbucket = "https://bitbucket.org/parsiya/" 48 | twitter = "https://twitter.com/cryptogangsta/" 49 | 50 | # --- End sidebar options --- 51 | 52 | # If set to true, navigation menu links will open in a new window with the exception of links to root ("/") 53 | # If this item does not exist or set to false, then navigation menu links will open in the same window 54 | navigationNewWindow = true 55 | 56 | # If false, all of blog post will appear on front page (and in pagination) 57 | truncate = true 58 | 59 | # Author's name (appears in meta tags and under posts) 60 | author = "Author" 61 | 62 | # This text appears in the site header under website title 63 | subtitle = "Subtitle appears under the website title" 64 | 65 | # Search engine URL 66 | searchEngineURL = "https://www.google.com/search" 67 | 68 | # Text of the "Continue Reading" label. Supports markdown and inline HTML. 69 | # For example, → == right arrow. 70 | continueReadingText = "Would you like to know more? →" 71 | 72 | # Switch to true to enable RSS icon link 73 | rss = true 74 | 75 | # Set to true to use a text label for RSS instead of an icon 76 | # This is overwritten by the "rss" setting 77 | textrss = false 78 | 79 | # Website's default description 80 | description = "" 81 | 82 | # 404.html header and text - both support markdown 83 | notFoundHeader = "There's nothing here" 84 | 85 | notFoundText = """Please either go back or use the navigation/sidebar menus. 86 | """ 87 | 88 | # Set to true to hide ReadingTime on posts 89 | disableReadingTime = false 90 | 91 | # Set to true to disable downloading of remote Google fonts 92 | disableGoogleFonts = true 93 | 94 | # Generate taxonomy pages 95 | generateTaxonomyList = true 96 | 97 | 98 | # Menu 99 | # If navigationNewWindow (under [params]) is set to true then all links except root ("/") will open in a new window 100 | # If it does not exist or is set to false then links will open in the same window 101 | [[menu.main]] 102 | Name = "example.net" 103 | URL = "https://www.example.net/" 104 | weight = -5 105 | 106 | [[menu.main]] 107 | Name = "This theme on Github" 108 | URL = "https://www.github.com/parsiya/hugo-octopress" 109 | 110 | 111 | # Sidebar menus 112 | # Enable with "sidebarMenuEnabled = true" under [params] 113 | # Header text is "sidebarMenuHeader" under [params] 114 | [[menu.sidebar]] 115 | Name = "example.net" 116 | URL = "https://www.example.net" 117 | weight = 0 118 | 119 | [[menu.sidebar]] 120 | Name = "This theme on Github" 121 | URL = "https://www.github.com/parsiya/hugo-octopress" 122 | weight = 1 123 | 124 | [markup] 125 | [markup.tableOfContents] 126 | endLevel = 8 127 | startLevel = 1 128 | [markup.highlight] 129 | style = "solarized-dark" 130 | -------------------------------------------------------------------------------- /exampleSite/content/page/about.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Single Page" 3 | date: "2021-02-14" 4 | url: "/about/" 5 | --- 6 | 7 | This is a single page. To create a page similar to this: 8 | 9 | 1. Create a new markdown file in `contents/page/about.md`. 10 | 1. Alternatively, create a [page bundle][page-bundle-link] `contents/page/about/index.md`. 11 | 2. In the frontmatter of the page, set the value of `url` to your desired relative path. 12 | 1. E.g., for this page we have `url = "/about/"`. 13 | 3. Now you can access the website at `baseurl/about` and you can link to it from the main menu or sidebar using the relative path. 14 | 15 | [page-bundle-link]: https://gohugo.io/content-management/page-bundles/ 16 | 17 | Linkify URL: https://example.net. It opens in a new tab only if using 18 | Blackfriday and not Goldmark (at the time of writing). 19 | 20 | markdown URL: [example.net](https://example.net). It should open in a new tab 21 | with both Blackfriday and Goldmark. 22 | -------------------------------------------------------------------------------- /exampleSite/content/post/goisforlovers.md: -------------------------------------------------------------------------------- 1 | +++ 2 | title = "(Hu)go Template Primer" 3 | description = "" 4 | tags = [ 5 | "go", 6 | "golang", 7 | "templates", 8 | "themes", 9 | "development", 10 | ] 11 | date = "2014-04-02" 12 | categories = [ 13 | "Development", 14 | "golang", 15 | ] 16 | +++ 17 | 18 | Hugo uses the excellent [go][] [html/template][gohtmltemplate] library for 19 | its template engine. It is an extremely lightweight engine that provides a very 20 | small amount of logic. In our experience that it is just the right amount of 21 | logic to be able to create a good static website. If you have used other 22 | template systems from different languages or frameworks you will find a lot of 23 | similarities in go templates. 24 | 25 | This document is a brief primer on using go templates. The [go docs][gohtmltemplate] 26 | provide more details. 27 | 28 | ## Introduction to Go Templates 29 | 30 | Go templates provide an extremely simple template language. It adheres to the 31 | belief that only the most basic of logic belongs in the template or view layer. 32 | One consequence of this simplicity is that go templates parse very quickly. 33 | 34 | A unique characteristic of go templates is they are content aware. Variables and 35 | content will be sanitized depending on the context of where they are used. More 36 | details can be found in the [go docs][gohtmltemplate]. 37 | 38 | ## Basic Syntax 39 | 40 | Go lang templates are html files with the addition of variables and 41 | functions. 42 | 43 | **Go variables and functions are accessible within {{ }}** 44 | 45 | Accessing a predefined variable "foo": 46 | 47 | {{ foo }} 48 | 49 | **Parameters are separated using spaces** 50 | 51 | Calling the add function with input of 1, 2: 52 | 53 | {{ add 1 2 }} 54 | 55 | **Methods and fields are accessed via dot notation** 56 | 57 | Accessing the Page Parameter "bar" 58 | 59 | {{ .Params.bar }} 60 | 61 | **Parentheses can be used to group items together** 62 | 63 | {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} 64 | 65 | 66 | ## Variables 67 | 68 | Each go template has a struct (object) made available to it. In hugo each 69 | template is passed either a page or a node struct depending on which type of 70 | page you are rendering. More details are available on the 71 | [variables](/layout/variables) page. 72 | 73 | A variable is accessed by referencing the variable name. 74 | 75 | {{ .Title }} 76 | 77 | Variables can also be defined and referenced. 78 | 79 | {{ $address := "123 Main St."}} 80 | {{ $address }} 81 | 82 | 83 | ## Functions 84 | 85 | Go template ship with a few functions which provide basic functionality. The go 86 | template system also provides a mechanism for applications to extend the 87 | available functions with their own. [Hugo template 88 | functions](/layout/functions) provide some additional functionality we believe 89 | are useful for building websites. Functions are called by using their name 90 | followed by the required parameters separated by spaces. Template 91 | functions cannot be added without recompiling hugo. 92 | 93 | **Example:** 94 | 95 | {{ add 1 2 }} 96 | 97 | ## Includes 98 | 99 | When including another template you will pass to it the data it will be 100 | able to access. To pass along the current context please remember to 101 | include a trailing dot. The templates location will always be starting at 102 | the /layout/ directory within Hugo. 103 | 104 | **Example:** 105 | 106 | {{ template "chrome/header.html" . }} 107 | 108 | 109 | ## Logic 110 | 111 | Go templates provide the most basic iteration and conditional logic. 112 | 113 | ### Iteration 114 | 115 | Just like in go, the go templates make heavy use of range to iterate over 116 | a map, array or slice. The following are different examples of how to use 117 | range. 118 | 119 | **Example 1: Using Context** 120 | 121 | {{ range array }} 122 | {{ . }} 123 | {{ end }} 124 | 125 | **Example 2: Declaring value variable name** 126 | 127 | {{range $element := array}} 128 | {{ $element }} 129 | {{ end }} 130 | 131 | **Example 2: Declaring key and value variable name** 132 | 133 | {{range $index, $element := array}} 134 | {{ $index }} 135 | {{ $element }} 136 | {{ end }} 137 | 138 | ### Conditionals 139 | 140 | If, else, with, or, & and provide the framework for handling conditional 141 | logic in Go Templates. Like range, each statement is closed with `end`. 142 | 143 | 144 | Go Templates treat the following values as false: 145 | 146 | * false 147 | * 0 148 | * any array, slice, map, or string of length zero 149 | 150 | **Example 1: If** 151 | 152 | {{ if isset .Params "title" }}

{{ index .Params "title" }}

{{ end }} 153 | 154 | **Example 2: If -> Else** 155 | 156 | {{ if isset .Params "alt" }} 157 | {{ index .Params "alt" }} 158 | {{else}} 159 | {{ index .Params "caption" }} 160 | {{ end }} 161 | 162 | **Example 3: And & Or** 163 | 164 | {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} 165 | 166 | **Example 4: With** 167 | 168 | An alternative way of writing "if" and then referencing the same value 169 | is to use "with" instead. With rebinds the context `.` within its scope, 170 | and skips the block if the variable is absent. 171 | 172 | The first example above could be simplified as: 173 | 174 | {{ with .Params.title }}

{{ . }}

{{ end }} 175 | 176 | **Example 5: If -> Else If** 177 | 178 | {{ if isset .Params "alt" }} 179 | {{ index .Params "alt" }} 180 | {{ else if isset .Params "caption" }} 181 | {{ index .Params "caption" }} 182 | {{ end }} 183 | 184 | ## Pipes 185 | 186 | One of the most powerful components of go templates is the ability to 187 | stack actions one after another. This is done by using pipes. Borrowed 188 | from unix pipes, the concept is simple, each pipeline's output becomes the 189 | input of the following pipe. 190 | 191 | Because of the very simple syntax of go templates, the pipe is essential 192 | to being able to chain together function calls. One limitation of the 193 | pipes is that they only can work with a single value and that value 194 | becomes the last parameter of the next pipeline. 195 | 196 | A few simple examples should help convey how to use the pipe. 197 | 198 | **Example 1 :** 199 | 200 | {{ if eq 1 1 }} Same {{ end }} 201 | 202 | is the same as 203 | 204 | {{ eq 1 1 | if }} Same {{ end }} 205 | 206 | It does look odd to place the if at the end, but it does provide a good 207 | illustration of how to use the pipes. 208 | 209 | **Example 2 :** 210 | 211 | {{ index .Params "disqus_url" | html }} 212 | 213 | Access the page parameter called "disqus_url" and escape the HTML. 214 | 215 | **Example 3 :** 216 | 217 | {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} 218 | Stuff Here 219 | {{ end }} 220 | 221 | Could be rewritten as 222 | 223 | {{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }} 224 | Stuff Here 225 | {{ end }} 226 | 227 | 228 | ## Context (aka. the dot) 229 | 230 | The most easily overlooked concept to understand about go templates is that {{ . }} 231 | always refers to the current context. In the top level of your template this 232 | will be the data set made available to it. Inside of a iteration it will have 233 | the value of the current item. When inside of a loop the context has changed. . 234 | will no longer refer to the data available to the entire page. If you need to 235 | access this from within the loop you will likely want to set it to a variable 236 | instead of depending on the context. 237 | 238 | **Example:** 239 | 240 | {{ $title := .Site.Title }} 241 | {{ range .Params.tags }} 242 |
  • {{ . }} - {{ $title }}
    • 243 | {{ end }} 244 | 245 | Notice how once we have entered the loop the value of {{ . }} has changed. We 246 | have defined a variable outside of the loop so we have access to it from within 247 | the loop. 248 | 249 | # Hugo Parameters 250 | 251 | Hugo provides the option of passing values to the template language 252 | through the site configuration (for sitewide values), or through the meta 253 | data of each specific piece of content. You can define any values of any 254 | type (supported by your front matter/config format) and use them however 255 | you want to inside of your templates. 256 | 257 | 258 | ## Using Content (page) Parameters 259 | 260 | In each piece of content you can provide variables to be used by the 261 | templates. This happens in the [front matter](/content/front-matter). 262 | 263 | An example of this is used in this documentation site. Most of the pages 264 | benefit from having the table of contents provided. Sometimes the TOC just 265 | doesn't make a lot of sense. We've defined a variable in our front matter 266 | of some pages to turn off the TOC from being displayed. 267 | 268 | Here is the example front matter: 269 | 270 | ``` 271 | --- 272 | title: "Permalinks" 273 | date: "2013-11-18" 274 | aliases: 275 | - "/doc/permalinks/" 276 | groups: ["extras"] 277 | groups_weight: 30 278 | notoc: true 279 | --- 280 | ``` 281 | 282 | Here is the corresponding code inside of the template: 283 | 284 | {{ if not .Params.notoc }} 285 |
    286 | {{ .TableOfContents }} 287 |
    288 | {{ end }} 289 | 290 | 291 | 292 | ## Using Site (config) Parameters 293 | In your top-level configuration file (eg, `config.yaml`) you can define site 294 | parameters, which are values which will be available to you in chrome. 295 | 296 | For instance, you might declare: 297 | 298 | ```yaml 299 | params: 300 | CopyrightHTML: "Copyright © 2013 John Doe. All Rights Reserved." 301 | TwitterUser: "spf13" 302 | SidebarRecentLimit: 5 303 | ``` 304 | 305 | Within a footer layout, you might then declare a `