# Hugo-Octopress Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hugo][hugo-link]. For a live demo please see my personal website at [https://parsiya.net](https://parsiya.net). ## Contents - [Config file parameters](#config) - [Code highlight](#highlight) - [Navigation menu](#menu) - [Markdown options](#markdown) - [CSS override](#cssoverride) - [Sidebar](#sidebarlinks) - [Sidebar text](#sidebartext) - [Social network icons](#sidebarsocial) - [Sidebar menu](#sidebarmenu) - [Recent posts](#sidebarrecent) - [Shortcodes](#shortcodes) - [Code caption](#codecaption) - [Image caption](#imgcap) - [Atom snippets for shortcodes](#snippets) - [Hugo page summary bug](#summary) - [License page](#licensepage) - [Table of contents](#tableofcontents) - [Not Found or 404.html](#notfound) - [Taxonomy pages](#taxonomy) - [Individual pages](#page) - [Disqus](#disqus) - [Issues/TODO](#issues) - [Attribution](#attribution) - [Ported by](#portedby) - [Theme license](#themelicense) ![screenshot](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/screenshot.png) ## Configuration Hugo-Octopress can be configured by modifying the parameters in the [configuration file](https://gohugo.io/overview/configuration/). A working config file `sample-config.toml` is provided. Some miscellaneous parameters are explained below: ``` toml baseurl = "http://example.com" disablePathToLower = false languageCode = "en-us" title = "Site title" theme = "hugo-octopress" # Disqus shortcode # Disable comments for any individual post by adding "comments: false" in its frontmatter disqusShortname = "Your disqus shortname" # Number of blog posts in each pagination page paginate = 6 [permalinks] # Configures post URLs post = "/blog/:year-:month-:day-:title/" # Make tags and categories work # As of Hugo v0.33 these are not needed anymore # [indexes] # tag = "tags" # category = "categories" [params] # If false, all of blog post will appear on front page (and in pagination) truncate = true # Author's name (appears in meta tags and under posts) author = "Author's name" # This text appears in site header under website title subtitle = "Subtitle appears under website title" # Search engine URL searchEngineURL = "https://www.google.com/search" # Text of the "Continue Reading" label. → == right arrow, but it gets messed up in the string so it was added to index.html manually continueReadingText = "Would you like to know more?" # Google analytics code - remove if you do not have/want Google Analytics - needs JavaScript googleAnalytics = "UA-XXXXX-X" # Optional piwik tracking #[params.analytics.piwik] # URL = "https://stats.example.com" # ID = "42" # Switch to true to enable RSS icon link rss = true # Set to true to use a text label for RSS instead of an icon # This is overwritten by the "rss" setting textrss = false # Website's default description defaultDescription = "" # Populate this with your own search keywords - these will appear in meta tags # defaultKeywords = ["keyword1" , "keyword2" , "keyword3" , "keyword4"] # Set to true to hide ReadingTime on posts disableReadingTime = false # Set to true to disable downloading of remote Google fonts disableGoogleFonts = false ``` ## Code highlight Octopress classic theme uses the pygments' `solarized dark` for highlighting. It is not installed by default. You can get it from https://github.com/john2x/solarized-pygment. It has three options: * solarized_light: default option after installation * solarized_dark: use this to re-create the Octopress classic theme highlighting * solarized_dark256 As on Hugo 0.28 the built-in Chroma highlighter is used by default. It does not support solarized dark yet. To keep using the highlighting by CSS add `pygmentsUseClassic=true` to the config file. The following options control code highlighting: ``` toml [params] # If nothing is set, then solarized_light is used pygmentsstyle = "solarized_dark" # Use internal highlighter instead of Chroma pygmentsUseClassic=true # Highlight shortcode and code fences (```) will be treated similarly pygmentscodefences = true # pygments options can be added here (and in the highlight shortcode in the markdown file) # Hugo supports these pygments options: style, encoding, noclasses, hl_lines, linenos # for example: pygmentsoptions = "linenos=true" ``` For more information see [Syntax Highlighting](https://gohugo.io/extras/highlighting/) in Hugo's documentation. ## Markdown options Blackfriday is Hugo's markdown engine. For a list of options see [Configure Blackfriday rendering](https://gohugo.io/overview/configuration/#configure-blackfriday-rendering). Blackfriday options can be set as follows: ``` toml [blackfriday] hrefTargetBlank = true # open the external links in a new window fractions = false ``` ## CSS override You can override the built-in CSS and use your own. Just put your own CSS files in the `static` directory of your website (the one in the theme directory also works but is not recommended for obvious reasons) and 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 your 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 configured here. Navigation menu is generated using the `layouts/partials/navigation.html` template. 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 be to the left of links with weights `0` or `10`. Links can be added to the config file like this: ``` 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 can also be customized: ``` toml [params] searchEngineURL = "https://www.google.com/search" ``` ## Sidebar Sidebar has four parts. From top to bottom it has: * Sidebar header and text (optional). * Social network icons (optional): Icons and links to Github, Bitbucket and more. * Sidebar menu (optional): Links in sidebar (I use them for internal category pages but you can have external links). * Recent posts: Displays last X (default is 5) posts. The sidebar is generated using the partial template at `layouts/partials/sidebar.html`. ### Sidebar text Sidebar text has two parts and both can be configured. Both values are passed to `markdownify` so you can use markdown (e.g. add links or new lines). * Sidebar header appears first in an `