# Hugo-Octopress Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hugo][hugo-link]. Live demo using the unmodified theme: * [http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/][live-demo]. * Source: [https://github.com/parsiya/Hugo-Octopress-Test][test-repo]. [live-demo]: http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/ [test-repo]: https://github.com/parsiya/Hugo-Octopress-Test My personal website with the compact index (see below): * [https://parsiya.net](https://parsiya.net). * Source: [https://github.com/parsiya/parsiya.net](https://github.com/parsiya/parsiya.net) ## Contents - [Quick start](#quick-start) - [Configuration](#configuration) - [Code highlight](#code-highlight) - [Goldmark vs. Blackfriday Markdown Engines](#goldmark-vs-blackfriday-markdown-engines) - [CSS override](#css-override) - [Navigation menu](#navigation-menu) - [Extending Headers and Footers](#extending-headers-and-footers) - [Sidebar](#sidebar) - [Sidebar text](#sidebar-text) - [Social network icons](#social-network-icons) - [Sidebar menu](#sidebar-menu) - [Recent posts](#recent-posts) - [Shortcodes](#shortcodes) - [Code caption](#code-caption) - [Image caption](#image-caption) - [Table of Contents](#table-of-contents) - [Pages](#pages) - [License page](#license-page) - [Not Found or 404.html](#not-found-or-404html) - [Taxonomy pages](#taxonomy-pages) - [Individual pages](#individual-pages) - [Table of contents](#table-of-contents-1) - [toc configuration](#toc-configuration) - [Use toc in Frontmatter](#use-toc-in-frontmatter) - [Use the toc Shortcode](#use-the-toc-shortcode) - [Editor Plugins](#editor-plugins) - [Disqus](#disqus) - [Twitter Card](#twitter-card) - [Compact Index](#compact-index) - [mainSections](#mainsections) - [Custom favicon](#custom-favicon) - [Troubleshooting](#troubleshooting) - [Hugo page summary bug](#hugo-page-summary-bug) - [Empty Posts Link on Homepage](#empty-posts-link-on-homepage) - [Issues/TODO](#issuestodo) - [Attribution](#attribution) - [Ported by](#ported-by) - [Theme license](#theme-license) ![screenshot](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/screenshot.png) ## Quick start Add the theme to your existing site or [Hugo's quick start][hugo-quickstart]. All commands are run from the root directory of your website. [hugo-quickstart]: https://gohugo.io/getting-started/quick-start/ If using git to manage your website, add the theme as a git submodule: ``` git submodule add https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress ``` Or you can clone it: ``` git clone https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress ``` To view the theme with the example site: ``` cd themes/Hugo-Octopress/ hugo serve -vw --source=exampleSite ``` And view the example website at http://localhost:1313. Example site was originally created by [https://github.com/nonumeros][nonumeros]. I reviewed the [pull request][examplesite-pr] almost two years late and had to copy/paste the website instead of resolving merge conflicts. The example website also has a page with the theme's shortcodes. [nonumeros]: https://github.com/nonumeros [examplesite-pr]: https://github.com/parsiya/Hugo-Octopress/pull/57 ## Configuration Hugo-Octopress can be configured by modifying the parameters in the [configuration file](https://gohugo.io/overview/configuration/). [sample-config.toml](sample-config.toml) and [exampleSite/config.toml](exampleSite/config.toml) are both working examples. ## Code highlight This theme uses the built-in [Chroma][chroma-link] highlighter with the `solarized-dark` theme. See all supported styles at [https://xyproto.github.io/splash/docs/all.html](https://xyproto.github.io/splash/docs/all.html). To change the style, change it in the config file like below to one of the supported styles. [chroma-link]: https://github.com/alecthomas/chroma Some options to control code highlighting post version `0.60`. ``` toml [markup] [markup.tableOfContents] endLevel = 8 startLevel = 1 [markup.highlight] style = "solarized-dark" ``` For more configuration options please see [https://gohugo.io/getting-started/configuration-markup/#highlight][hugo-configuration-markup] and [https://gohugo.io/extras/highlighting/][hugo-syntax-highlighting] in Hugo's documentation. [hugo-syntax-highlighting]: https://gohugo.io/extras/highlighting/ [hugo-configuration-markup]: https://gohugo.io/getting-started/configuration-markup/#highlight ## Goldmark vs. Blackfriday Markdown Engines Prior to version `0.60`, Hugo used Blackfriday. Now it uses Goldmark by default. See https://gohugo.io/getting-started/configuration-markup#highlight for information about setting it up. There are trade-offs. Mainly, the `hrefTargetBlank` Blackfriday extension. It was set to true to open external links in a new browser tab. Unfortunately, Goldmark does not have this built-in. To make it happen, we need to use a render hook. I used the one in Hugo docs at https://gohugo.io/getting-started/configuration-markup#link-with-title-markdown-example. This works for markdown links but not linkify or image links. Linkify links are straight URLs pasted into the document (e.g., `https://example.net`). A workaround is not having links similar to this (which is not in the markdown standard anyways) and use normal links. For example, `[example.net](https://example.net)` or reference links. You can keep using Blackfriday like this: ``` toml [markup] defaultMarkdownHandler = "blackfriday" [markup.blackFriday] hrefTargetBlank = true ``` ## CSS override You can override the built-in CSS and add your own. Put your CSS files in the `static` directory of your website. While storing them inside the `themes/Hugo-Octopress/static` directory works, it's not recommended (keep your website and theme as separated as possible to be able to switch themes easily). Then modify the `customCSS` parameter. The path should be relative to the `static` folder. These CSS files will be added through the `header` partial after the built-in CSS file. For example, if custom CSS files are `static/css/custom.css` and `static/css/custom2.css` then `customCSS` will look like this: ``` toml [params] customCSS = ["css/custom.css","css/custom2.css"] ``` ## Navigation menu Links in the navigation menu (everything other than Google search and RSS icon) can be customized. The navigation menu is generated using the `layouts/partials/navigation.html` partial. By default, navigation menu links will open in the same window. You can change this behavior by setting the `navigationNewWindow` parameter to true. Links to root ("/") will always open in the same window. Currently, Hugo does not support adding custom attributes to menus. Links are sorted according to weight from left to right. For example, a link with weight of `-10` will appear to the left of links with weights `0` or `10`. Links can be added to the config file: ``` toml [[menu.main]] Name = "Blog" URL = "/" weight = -10 [[menu.main]] Name = "The other guy from Wham!" URL = "https://www.google.com/search?q=andrew+ridgeley" weight = -5 [[menu.main]] Name = "This theme - add link" URL = "https://www.github.com" [params] # If set to true, navigation menu links will open in a new window with the exception of links to root ("/") # If this item does not exist or is set to false, then navigation menu links will open in the same window navigationNewWindow = true ``` Search engine customization: ``` toml [params] searchEngineURL = "https://www.google.com/search" ``` ## Extending Headers and Footers Copy these files from `theme/Hugo-Octopress/layouts/partials/` into `your-site/layouts/partials` and modify them: * `extend_header.html`: Everything will be added to the end of the `head` tag on every page. * `extend_footer.html`: Everything will be added after the `footer` tag on every page. ## Sidebar The sidebar has four sections, from top to bottom: * Sidebar header and text (optional). * Social network icons (optional): Icons and links to GitHub, Mastodon, and more. * Sidebar menu (optional): Links in sidebar. * Recent posts: Displays last X posts (default is 5). The sidebar is generated using the partial at `layouts/partials/sidebar.html`. ### Sidebar text The sidebar text has two parts and both can be configured. Both are passed to `markdownify` so you can use markdown (e.g. add links or new lines). * Sidebar header appears first in an `