# 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/](http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/). * Source: [https://github.com/parsiya/Hugo-Octopress-Test](https://github.com/parsiya/Hugo-Octopress-Test). My personal website uses 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 - [Configuration](#configuration) - [Code highlight](#code-highlight) - [Markdown options](#markdown-options) - [CSS override](#css-override) - [Navigation menu](#navigation-menu) - [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) - [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) - [Disqus](#disqus) - [Twitter Card](#twitter-card) - [Compact Index](#compact-index) - [mainSections](#mainsections) - [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) ## 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/" [params] # If false, all contents of posts will appear on the 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. Supports markdown and inline HTML. # For example, → == right arrow. 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 description = "" # Populate with your 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 # Remove or set to false to use local fonts remoteFonts = false # Remove or set to false to use FontAwesome CDN, otherwise, the theme uses ForkAwesome local fonts. # fontAwesome = false ``` ## Code highlight This theme uses the built-in [Chroma](https://github.com/alecthomas/chroma) 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). Some options to control code highlighting: ``` toml # Highlight shortcode and code fences (```) will be treated similarly pygmentscodefences = true # Change highlight style here. # Full list: https://xyproto.github.io/splash/docs/all.html pygmentsStyle = "solarized-dark" # Add other Chroma options here (override them in the highlight shortcode inside markdown) # List of supported options: https://gohugo.io/content-management/syntax-highlighting/#options # 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 complete list of options see [Configure Blackfriday rendering](https://gohugo.io/getting-started/configuration/#configure-blackfriday-rendering). Blackfriday options can be set as follows: ``` toml [blackfriday] hrefTargetBlank = true # open external links in a new window fractions = false ``` ## 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" ``` ## Sidebar The sidebar has four sections, from top to bottom: * Sidebar header and text (optional). * Social network icons (optional): Icons and links to Github, Bitbucket, 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 `