hugo-icarus is a responsive and customizable blog theme for the Hugo static site generator, ported from Hexo's Icarus theme originally created by Ruipeng Zhang and maintained here by Tory S. Anderson.
What is hugo-icarus?
hugo-icarus is a Hugo theme that turns a standard Hugo site into a blog with a left profile sidebar, a right widgets sidebar, and a clean article layout. It takes a Hugo site's content files and config.toml as input, and produces a fully static, responsive blog with features like Disqus comments, syntax highlighting, and MathJax equation rendering. The theme is distributed as a Git repository on GitLab and installed by cloning into a Hugo project's themes directory.
Key features
- Disqus comments — Enable comments by setting
disqusShortnamein config.toml; individual pages can opt out withdisable_comments = truein front matter. - Localization (l10n) — All UI strings live in
data/l10n.toml, so translating the theme is a matter of replacing those strings. - Sidebar widgets — Four optional widgets are built in: recent articles, category list, tag list, and tag cloud; each can be toggled under
[params.widgets]. - Profile sidebar — A left-hand profile section automatically builds social media links from a
sociallist in config.toml. - MathJax support — LaTeX and MathML equations render out of the box; wrap LaTeX in
$$(display) or$(inline), and disable the library withdisable_mathjax = true. - Gallery shortcode — A
{{< gallery >}}shortcode accepts relative paths to images and renders them as a gallery inside any content page. - Front matter controls — Pages can hide the profile (
disable_profile), widgets (disable_widgets), the date line (nodateline), and previous/next links (noprevnext). - Banner thumbnails — Each post can define a banner by setting a relative image path, such as
banner = "banners/placeholder.png".
Who is it for?
- Bloggers using Hugo who want a ready-made two-column layout with a personal profile and tag/category navigation.
- Technical writers who publish code-heavy posts benefit from built-in syntax highlighting and MathJax for mathematical formulas.
- Multilingual website owners who need to translate the theme interface can do so directly through the l10n data file.
What can you do with hugo-icarus?
- Personal bloggers can start a blog quickly by cloning the theme, copying the exampleSite configuration, and running
hugo serverto preview locally at localhost:1313. - Academic or math-oriented authors can write posts containing LaTeX equations and have them rendered by MathJax without extra configuration.
- Photographers can use the gallery shortcode to embed image collections into posts, storing images in the content folder or the static directory.
How does hugo-icarus work?
Installation follows the standard Hugo theme workflow: run git clone https://gitlab.com/toryanderson/hugo-icarus.git inside the themes folder of a Hugo site, then copy config.toml and the contents of data/ from the theme's exampleSite to your site root. The exampleSite sets themesDir = "../.." so it can run standalone; production sites must comment out that property to avoid theme lookup failures.
FAQ
Is hugo-icarus free?
Yes, the theme is released under the MIT license, as stated in the README and LICENSE.md.
How do I enable Disqus comments?
Set your Disqus shortname in config.toml as disqusShortname = "your-shortname". For a single page, add disable_comments = true to its front matter to hide the comment section.
Does hugo-icarus support equations?
Yes. MathJax is included and handles both LaTeX and MathML. LaTeX blocks are wrapped in $$ and inline math in $; you can disable the whole system by setting disable_mathjax = true in config.toml.
What widgets are available?
The right sidebar can show recent articles, a category list, a tag list, and a tag cloud. Each is toggled independently via the [params.widgets] section in config.toml.
Is this theme still maintained?
The repository is a fork that fixes issues in the original unmaintained Hugo Icarus theme, including front-page post listing, recent posts, and post counts. The last commit visible in the repository is from July 2020.
