Hugo-Octopress

Hugo-Octopress is a Hugo theme that ports the classic Octopress blogging theme to the Hugo static site generator, giving Jekyll-era blog design to Hugo users.

What is Hugo-Octopress?

Hugo-Octopress is an open-source theme that recreates the classic Octopress design — originally built for Jekyll by Brandon Mathis — inside Hugo. It takes standard Hugo markdown content with YAML/TOML frontmatter and outputs a static blog with a two-column layout: a configurable sidebar plus a main content area. The theme is maintained by Parsia (parsiya.net), released under the MIT license, and available on GitHub. It works with Hugo's built-in templating and supports both Goldmark and Blackfriday markdown engines.

Key Features

• Configurable sidebar — The sidebar has four optional sections: header/text, social network icons (GitHub, Mastodon, Twitter, LinkedIn, and more), a custom menu, and a recent-posts list whose count is set via sidebarRecentLimit.
• Custom shortcodes — Includes codecaption to add titles and line numbers to code blocks, imgcap to add captions to images, and toc to drop a table of contents anywhere in a page.
• Multiple table-of-contents paths — Add a ToC via frontmatter (toc: true), globally via the tableOfContents parameter, or with the toc shortcode; heading levels are configurable in the markup settings.
• Syntax highlighting — Uses the built-in Chroma highlighter with the solarized-dark style by default; the style can be changed in the config file to any Chroma-supported style.
• Disqus and Twitter Card integration — Comment support with per-page opt-out (comments: false) and Twitter Card metadata via parameters like twitterCardEnabled, twitterCardDomain, and twitterImage.
• Customization hooks — Override the theme's CSS by listing files in customCSS, replace the favicon through the favicon parameter, and extend all pages by copying extend_header.html and extend_footer.html into your site's partials.
• Compact index mode — Set compactIndex = true to replace full post summaries on the homepage with a dense one-line list, and use mainSections to select which content sections appear on the main page.

Who is it for?

• Bloggers who want the distinctive Octopress look on a modern Hugo site without writing templates from scratch.
• Former Octopress users migrating from Jekyll to Hugo can preserve the visual style of their old blog while gaining Hugo's faster builds.
• Technical writers can use the sidebar to surface recent posts, category links, and social profiles, and the ToC shortcode to anchor long articles.

What can you do with it?

• Personal blogs: Set up a multi-section blog with posts, tags, and categories, and add a compact index for a minimalist homepage.
• Technical documentation: Use the codecaption and imgcap shortcodes to annotate code examples and screenshots, and place a table of contents via the toc shortcode.
• Customized sites: Extend the header and footer partials, swap the favicon, load your own CSS files, and rearrange sidebar social icons by copying social.html into your site's partials.

How does it work?

Install the theme by cloning it into themes/Hugo-Octopress or adding it as a git submodule, then set theme = "Hugo-Octopress" in your site's config. Configuration is done in config.toml with documented parameters for the sidebar, navigation, social icons, Twitter cards, and more. Write content as markdown files in content/ — optionally with frontmatter flags like toc, comments, or twitterImage — and run hugo to generate the static site.

Pros and cons

• Pros: Free under the MIT license; closely follows the original Octopress HTML/CSS so the classic look is preserved; configurable without editing theme code thanks to parameters and partial overrides; supports modern Hugo features like Chroma highlighting and Goldmark.
• Cons: The bundled CSS is roughly 53 KB and over 2,300 lines, taken largely unchanged from Octopress, so it contains dead code and is hard to maintain; Goldmark lacks the hrefTargetBlank extension, so opening external links in a new tab needs a custom render hook.

Pricing

Hugo-Octopress is free and open source under the MIT license.

Alternatives

• Octopress — the original theme for Jekyll that this theme ports; if you stay on Jekyll you can use it directly.
• Hyde-x — another Hugo theme that contributed code and the social-icon idea to Hugo-Octopress.

FAQ

Is Hugo-Octopress free?

Yes, the theme is open source under the MIT license, so you can use, modify, and redistribute it freely.

How do I add a table of contents to a post?

You can enable it globally with tableOfContents = true under [Params], set toc: true in a post's frontmatter, or insert the toc shortcode wherever you want the ToC to appear in the body.

How do I enable the compact index?

Set compactIndex = true under [Params] in your config file. To return to the classic view, remove the parameter or set it to false.

Does the theme support comments?

Yes, it supports Disqus. Configure your Disqus shortname in the config file and add comments: false to individual pages to disable comments for that page.