1bl4z3r/hermit-v2

Continuing Hermit's legacy to be minimal and fast theme

hermit-V2 -: The Minimal Hugo Theme

hermit-V2 is a minimal and fast theme for Hugo, built for bloggers who want a simple and focused website. This is a maintained fork of Hermit, which iterates over the original work to have production-ready experience with bug fixes and new features.

History

When I had switched from Jekyll to Hugo, I was in a need of a theme. I was enthralled by this very theme, and I am using it since in my own personal blog. However, it looks like OP has stopped maintaining this theme and as a result, it is riddled with bugs and code breaks. Hence, I have taken upon myself to maintain this theme.The intention of this project is to keep the essence of the theme as-it-is and only add minor updates and squash bugs which may arise.

GoHugo Theme Page : https://themes.gohugo.io/themes/hermit-v2/

Demo

Demo page https://1bl4z3r.github.io/hermit-V2, which is both demo and documentation for the theme, is located in Staging Branch

Configuration Guide

Configuration Guide is present in Explaining Configs

Installation

Run this command from the root of your Hugo directory:

git clone https://github.com/1bl4z3r/hermit-V2 themes/hermit-v2

Or, if your Hugo site is already in git, you can include this repository as a git submodule. This makes it easier to update this theme. For this, you need to run:

git submodule add -b main https://github.com/1bl4z3r/hermit-V2 themes/hermit-v2

To update submodule and to have the latest version of the theme with your project, run

git submodule update --remote

Sites using hermit-V2

Sites using hermit-V2 is a user contributed list of all the blogs/pages that is using hermit-V2 in some capacity. It could be any component of the theme from landing page or a partial to full fledged use of the theme. The objective of this section is to :

• Help new and aspiring bloggers/webmasters to get inspiration from
• Create a sense of community

You can find currently listed sites from Sites-using-hermit‐V2 and you can add your site by raising an issue for the same.

First Use Knowledge

Features Inherited from Original Theme

• A single-column layout and carefully crafted typography offers a great reading experience.
• Navigation and functions are placed in the bottom-bar which will hide when you scroll down.
• Featured image is supported. It will be displayed as a dimmed background of the page.
• Displays all of your posts on a single page, with one section per year, simple and compact.
• Extremely lightweight and load fast. No third party framework, no unnecessary code.
• All code fields feature syntax highlighting and a code-copy function
• Responsive & Retina Ready. Scales gracefully from a big screen all the way down to the smallest mobile phone. Assets in vector format ensures that it looks sharp on high-resolution screens.

Configuration

Site Configuration is done through hugo.toml or hugo.yaml file in root directory of your Hugo Site. To aid you, there is a hugo.toml.example file located in theme folder. See this configuration in action here. See what each configuration does here.

Custom CSS and JS

I have found that there are some requirements where custom CSS and JS should be supplied to a page to make it work. This custom files are not required for the whole of the site, but is restricted to a page or few particular pages. E.g. If you make contact form.

To make use of custom CSS and JS, add the below section to page frontmatter. If there is any folder structure, that should be mentioned as well.

custom_css = ["custom_css/foo.css","custom_css/bar.css"]
custom_js = ["custom_js/custom-about.js"]

The files itself will reside in assets directory. Refer to Staging Branch to have a feel on how this is implemented.

Favicon

Use RealFaviconGenerator to generate these files, put them into your site's static folder:

• android-chrome-192x192.png
• android-chrome-512x512.png
• apple-touch-icon.png
• favicon-16x16.png
• favicon-32x32.png
• favicon.ico
• mstile-150x150.png
• safari-pinned-tab.svg
• site.webmanifest

SVG Favicons

If your favicon is in SVG format, there are two ways to implement the same in this theme.

• If you are looking for a clean directory structure, place your favicon as favicon.svg in static directory. In this mode, favicon will not be minified by Hugo
• If you want your generated site to be as light as possible, place your favicon as favicon.svg in assets/images. In this mode, favicon will be minified by Hugo

Social icons

The following icons are supported, please make sure the name field is exactly one of these:

name
email	codepen	facebook	github
gitlab	instagram	linkedin	slack
stackoverflow	telegram	twitter	youtube
shutterstock	freepik	adobestock	123rf
dreamstime	dribbble	behance	paypal
twitch	qq	mastodon	discord
etsy	tiktok	imgur	bluesky
medium	medium old

If that's not enough, you can see Overriding templates section.

Manage content

• Keep your regular pages in the content folder. To create a new page, run hugo new page-title.md
• Keep your blog posts in the content/posts folder. To create a new post, run hugo new posts/post-title.md

Overriding templates

In Hugo, layouts can live in either the project’s (root) or the themes’ layout folders, any template inside the root layout folder will override theme's layout that relative to it, for example: layouts/_default/baseof.html will override themes/hermit/layouts/_default/baseof.html. So, you can easily customize the theme without edit it directly, which makes updating the theme easier. Here are some common customizations:

Customize social icons

You can modify or add any SVG icons in site's layouts/partials/svg.html.

Customize comment system

We only have built-in support for Disqus at the moment, if that doesn't fit your needs, you can just add HTML to site's layouts/partials/comments.html.

Add custom analytics

If you prefer to use different analytics system other than Google Analytics, then add them inside layouts/partials/analytics.html.

Customize CSS

1. Change predefined colors/effects - If you'd like to customize theme color or fonts, you can simply override assets/scss/_predefined.scss, by simply copy it to site's root (keep the same relative path) then edit those variables.
2. Change CSS effects limited to single page or few pages - Add following to your page FrontMatter custom_css = ["custom_css/foo.css","custom_css/bar.css"], and add the relevant SCSS files in assets directory. You may find additional help in Custom CSS and JS.
3. Change css styling sitewide - If you are unhappy with how the theme looks and feels and want to change some (or all) of it to make it truly your own, you can do so by adding assets/scss/userstyles.scss to your site's root and modify Stylesheets to your liking.

You'll need Hugo extended version, which has the ability to rebuild SCSS. You don't have to use extended version in production, but in this case it's necessary to make sure the resources folder is committed and "up to date" (by running hugo or hugo server locally using the extended version). But anyway, always use the extended version if you can.

Code injection

You can inject any HTML code to every page's document head or right above the closing body tag. This makes it easier to add any HTML metadata, custom css/js, DNS-prefetch etc. To do this you simply need to create a file at site's layouts/partials/extra-head.html or layouts/partials/extra-foot.html, code inside will be injected to every page.

LaTeX in Markdown

LaTeX is supported by this theme through Mathjax. Please check explaining-configs to learn more.

Acknowledgments

• normalize.css - MIT
• animate.css - MIT
• feather - MIT
• code-copy.js - Tom Spencer
• Everyone, who has submitted a PR

hermit-v2's Issues

Request: ability to disable last modified timestamp

I see this is part of single.html in v1.0.2, where it has an if .Lastmod conditional.

Any chance we can expose a new config parameter to turn off this behavior? I like the default "creation only" timestamp. Alternately, maybe a post front matter parameter could be useful too

[feature request] A wechat icon (or actually, an icon tutorial?)

Hi.

I'm using hermit previously and found hermit-v2 last weekend. Thank you @1bl4z3r for releasing this, and there are a lot of new exciting features.

There are a lot of social icon available, but it's always not enough, as people in different area / country may use different social media. I customized a WeChat icon in my hermit blog. Since hermit-v2 imports "share" feature, it's not working well in main page and share button (at the same time).

So I would like to know how a suitable social icon could be created, and what's the guideline I should follow with, so that we don't have to do "feature request" but just submit a pull request to add support for hermit-v2.

Here I have some svg examples of WeChat. (codes here and here ). I would like to ask what size (height & weight) / color / etc... should I use

[BUG] - Minify svg icon with hugo

Describe the bug
Hugo is capable of minifying svg files: https://gohugo.io/hugo-pipes/minification/

For this to work, the svg file simply need to be treated like other assets, such as custom CSS.

Changes in 4e7988b011e1dce93e9b7e8e0704a0220cf7dcdf

Hello,

Changes made in commit 4e7988b.

1. Rename config.toml to hugo.toml. Reference https://gohugo.io/getting-started/configuration/#hugotoml-vs-configtoml
2. Made a new branch called deploy, which will be used to push changes from my end and help to create a hostable site on Github Pages

Add to Sites using hermit-V2

• Site Name : Adam H. Sparks
• Site URL : https://adamhsparks.netlify.app/
• Add / Edit my site
  Description : Biometry, agricultural data analysis, systems and plant disease modelling, and professional cat herding

Feature request: share button

It would be cool to support a share button at the bottom of posts. It could be an opt-in feature, or enabled by default.

https://discourse.gohugo.io/t/share-buttons-for-blog-posts/12384 is a forum post with some ideas, the best seems to be https://codingnconcepts.com/hugo/social-icons-hugo/.

Thanks for your consideration, let me know what you think

LinkedIn Share button not working

When turning on shareSocial in my config, I observed the LinkedIn share isn't working for me. When I click the link, here's what I get:

When running hugo server -D, here is the URL behind the LinkedIn icon that leads to this error page: https://www.linkedin.com/shareArticle?mini=true&url=http%3a%2f%2flocalhost%3a1313%2ftags%2f&title=Tags&summary=Tags%2c%20by%201248%0a%3cnil%3e%0a%0ahttp%3a%2f%2flocalhost%3a1313%2ftags%2f%0a&source=http%3a%2f%2flocalhost%3a1313%2f

themeColor in hugo.toml does not appear to function as expected

Hi!

Maybe I'm misunderstanding the purpose of the themeColor option in hugo.toml, but I can't get it to work as it should.

In the example, this is set to '#494f5c'

hermit-V2/hugo.toml.example

Line 68 in 93f7434

themeColor = "#494f5c"

And this does match the background colour I get when I use this value in my hugo.toml. But if I change this value, I can't see what changes.

From what I can tell, most of the theme colour values are hard-coded in _predefined.scss:

hermit-V2/assets/scss/_predefined.scss

Lines 2 to 7 in 93f7434

	$theme: #018574;
	$text: #e8eef2;
	$light-grey: #494f5c;
	$dark-grey: #3B3E48;
	$highlight-grey: #7d828a;
	$midnightblue: #2c3e50;

And I can't really see where themeColor actually gets used, apart from here:

hermit-V2/layouts/partials/site-meta.html

Line 14 in 93f7434

{{ with .Site.Params.themeColor -}}

But I'm not sure it's working correctly. Any ideas?

Can not build on hugo v0.120.x

hugo v0.120.1 was rolled out yesterday and my Ubuntu snap package force-updated from v0.119.x.

Now I get the following errors when trying hugo serve:

ERROR render of "taxonomy" failed: "/home/aron/dev/rasterra/hermit-V2/layouts/_default/baseof.html:13:4": execute of template failed: template: _default/list.html:13:4: executing "_default/list.html" at <partial "structured-data.html" .>: error calling partial: execute of template failed: template: _internal/opengraph.html:47:9: executing "_internal/opengraph.html" at <site>: can't evaluate field facebook_admin in type []interface {}
Error: error building site: render: failed to render pages: render of "home" failed: "/home/aron/dev/rasterra/hermit-V2/layouts/_default/baseof.html:13:4": execute of template failed: template: index.html:13:4: executing "index.html" at <partial "structured-data.html" .>: error calling partial: execute of template failed: template: _internal/opengraph.html:47:9: executing "_internal/opengraph.html" at <site>: can't evaluate field facebook_admin in type []interface {}

The problem

in v0.120.0 they deprecated site.Social in favor of site.Params.social.
Internal templates like _internal/opengraph.html are now looking for parameters there. (see gohugoio/hugo@4910312)
This collides with the definition in theme's hugo.toml. (array of social media links)

Internal templates do not expect an array, so we get the error above.

Proposed solution

Probably to change [[params.social]] entries in hugo.toml to something else e.g. [[params.socialLinks]].
The site builds fine when I change or remove said entries.

Request: linking example site's source in `README`

I am not finding it obvious where the source content underlying the example site is: https://1bl4z3r.github.io/hermit-V2/

Can a link be posted in the README for the example site?

Request: example site's GitHub button pointing to this repo

The demo site's GitHub icon here: https://1bl4z3r.github.io/hermit-V2/

Instead of just pointing to https://github.com/, can we have it take us to either:

• This repo
• Example site's source code

Thank you in advance!

LaTeX not functional

Hello! While going through the demo website I've noticed that the LaTeX is no longer working and isn't showing up anymore. It can be seen here: https://1bl4z3r.github.io/hermit-V2/posts/typography/. Here is what I'm seeing on my end: https://i.imgur.com/xKxJfZa.png
I am using LibreWolf on Windows 10.

Few icons don't render.

Discord, Twitter and few other icons don't render properly for me.

How it looks on my website.

Code snippet from the Elements:

[BUG] If RSS is disabled (Add "RSS" to disableKinds), the footer RSS icon is still visible and leads to a 404 page

Describe the bug
After disabling RSS in hugo.toml via disableKinds = ["RSS"], the footer RSS icon is still visible, and it links to a 404 page.

To Reproduce
Steps to reproduce the behavior:

1. Add disableKinds = ["RSS"] to hugo.toml.
2. Build the site.
3. Note that the RSS icon is visible and clicking on it leads to a 404 page.

Expected behavior
RSS icon should become invisible.

Hugo (please complete the following information):

• Hugo: v0.124.1
• Extended? yes
• Latest hermit-V2 theme package? yes

Very happy to see this!!

I am a fan of Hugo's Hermit theme, and use it for my blog onetwofoureight.com.

I was going to change theme to one with a page sharing feature, however, I came across this today. And coincidentally, the v1 release was this morning, haha wow!

Very excited to transition to this, cheers!

Request: repositioning `post-end` when `legacyLayout = true`

When legacyLayout = true, I find the post-end bar seems to be in the wrong place. See the below screenshot:

I think a few options for when legacyLayout = true:

• Disable post-end in favor of art-end
• Disable art-end and move post-end above the metadata (what hermit v1 has)

What do you think? Thanks in advance

Remove language code from the URL

I'm not using any of the i18n features, is it possible to remove /en/ from the urls?

[BUG] - Allow svg as the favicon

The path to favicon is hardcoded as favicon.ico. svg can't be used here.

By allowing an svg favicon, the favicon can color itself based on browser theme (light, dark, etc.). See this blog post for a quick example: https://www.billerickson.net/favicon-dark-mode/

Migration from hermit to hermit-V2 complete, adopted!

I have fully migrated to hermit-V2 theme for onetwofoureight.com (GitHub repo). Thanks for making this theme!

Request: `index.html` using `footer.html` partial

In #28 I was able to override my footer.html partial.

However, I discovered index.html doesn't use the footer.html partial. Can we move index.html to either:

• Move home-footer.html to a partial that can be overridden
• Have index.html use the footer.html partial

Thank you in advance for your consideration

Placing post metadata on bottom of post

The original hermit theme placed post metadata like tags, Git commit, and word count on the bottom of the post.

It seems hermit-V2 is placing that metadata on the top of a post. Is there any way to control if metadata goes at the top or bottom or the page?

Add to Sites using hermit-V2

• Site Name : 8 Hobbies
• Site URL : https://www.8hobbies.com
• Add / Edit my site
  Description : Homepage of 8 Hobbies, dedicated to web technology and open source.
• Remove my site
  Please remove my site from Sites using hermit-V2 wiki

Request: configuration reference table

Check out https://blowfish.page/docs/configuration/, it has a sequence of tables that document hugo.toml or frontmatter parameters:

• Name
• Default
• Description

It would be nice if Hermit-V2 had a similar post documenting configuration parameters with defaults/descriptions

Unintended side effect of `[params.author]`

The fix in 556699f has a side effect, which is my site starts using the hermit-V2's about option from the repo's hugo.toml:

hermit-V2/hugo.toml

Line 41 in 556699f

about = "about-hugo"

It leads to this error:

> hugo server -D
...
hugo v0.120.3-a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970+extended darwin/arm64 BuildDate=2023-11-01T17:57:00Z VendorInfo=gohugoio

ERROR [en] REF_NOT_FOUND: Ref "about-hugo" from page "posts/post-title.md": page not found

The issue arises because my About post in content/ is not named about-hugo, it's just named about.

Fix option 1 (falls onto users): when migrating to [params.author], one has to override both name and about:

[params.author]
name = "James Braza"
about = "about"

Fix option 2 (falls onto hermit-v2): removing the [params.author] section from the main branch's hugo.toml

What do you think? I am not sure which is the better route.

Update README

Update README so that new users can install your repo as a git submodule instead of still using the original repo.

[BUG] - 404 page should include a `noindex` meta

Describe the bug

404 page should not be indexed by the search engine. Per https://developers.google.com/search/docs/crawling-indexing/block-indexing, this can be done by adding a noindex meta to the page.

Even though this page does not appear in sitemap.xml and search engine won't discover it in the first place, but if someone posts a misspelled link to the site somewhere else, search engines would inadvertently indexed the page through the link.

[BUG] - Error: error building site: render: failed to render pages

Describe the bug

I've upgraded hermit-V2 theme in my blog from v1.0.5 to the latest - v1.1.4
and the build had failure (detailed output in Terminal Output section),
as my understanding the problem is here:

https://github.com/1bl4z3r/hermit-V2/blob/main/layouts/_default/baseof.html#L19

{{ $c_css := resources.Get . | resources.ExecuteAsTemplate "css/style.css" $rootCtx | toCSS | minify | fingerprint -}}

I'm surprised because as I see empty css/style.css exists in theme,
maybe this is misconfiguration of hugo (my fault) or blog configuration conflict to theme, but all works find before (on v.1.0.5).

Could you please check it?

hermit changes

To Reproduce
Have no idea, it seems the fastest way to reproduce the bug its just clone the blog and run hugo build:

1. Clone https://github.com/1buran/blog (it is not large - 1 post and little bit of css)
2. Run hugo build

Terminal Output

$ hugo -Dw --logLevel debug server
Watching for changes in /home/buran/projects/blog/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /home/buran/projects/blog/hugo.toml
Start building sites … 
hugo v0.123.7+extended linux/amd64 BuildDate=unknown

INFO  build:  step process substep collect files 3 files_total 3 duration 2.11206ms
INFO  build:  step process duration 2.368108ms
INFO  build:  step assemble duration 3.116779ms
INFO  static: syncing static files to / duration 15.526749ms
INFO  deprecated: .Site.DisqusShortname was deprecated in Hugo v0.120.0 and will be removed in a future release. Use .Site.Config.Services.Disqus.Shortname instead.
INFO  build:  step render pages 13 content 10 duration 108.256449ms
INFO  build:  step postProcess duration 8.529µs
INFO  build:  duration 114.262578ms
Built in 115 ms
Error: error building site: render: failed to render pages: render of "page" failed: "/home/buran/projects/blog/themes/hermit-v2/layouts/_default/baseof.html:19:40": execute of template failed: template: _default/single.html:19:40: executing "_default/single.html" at <resources.ExecuteAsTemplate>: error calling ExecuteAsTemplate: type <nil> not supported in Resource transformations

Expected behavior
Missed css/style.css should not be cause build failure.

Hugo (please complete the following information):

• Hugo: v0.123.7+extended
• Extended? yes (Im not sure what does this mean, answered based on hugo version suffix)
• Latest hermit-V2 theme package? yes

Additional context
Archlinux

Request: ability to disable "Made with Hugo" in `footer.html`

When migrating from Hermit to Hermit-V2, looking at footer.html, it seems there is a change where it add "Made with Hugo" and "Theme Hermit-V2":

Any chance you'd be willing to add a config flag to disable those additions? I prefer to have a smaller footer.

---

Trying to copy layouts/partials/footer.html into my own project dir, and modify it myself for now, I get the below error when running hugo server -D:

Error: error building site: TOCSS: failed to transform "css/style.css" (text/x-scss). Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.: this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information

So maybe if you don't want to add new config flags, how can I override the layouts/partials/footer.html myself?

Request: code block limiting width with scroll bar

As of version 1.0.0, looking at the example site's MathJax post: https://1bl4z3r.github.io/hermit-V2/posts/mathjax-support/

The left/right scrolling is huge due to the first code block in the configuration section.

Any thoughts on having the scrolling limited to within the code block (and not the entire page)?

As an example, check out the code blocks here work (left/right scrolling is scoped to the code block): https://blowfish.page/docs/shortcodes/#alert

File to import not found or unreadable: userstyles.scss.

I keep getting the following error when trying to use a userstyles.scss file.

Error: error building site: TOCSS: failed to transform "css/style.css" (text/x-scss): "/home/uzair/Documents/git/test/themes/hermit-v2/assets/scss/style.scss:10:1": File to import not found or unreadable: userstyles.scss.

I have my userstyles.scss file under assets/scss/ as per the README but I see that userstyles.scss is being checked at assets/scss/userstyles.scss and then it tries to import userstyles.scss from the project root.

hermit-V2/assets/scss/style.scss

Lines 9 to 11 in 630960e

	{{ if (fileExists "assets/scss/userstyles.scss") }}
	@import "userstyles.scss";
	{{ end }}

If I create an empty userstyles.scss in assets/scss/ folder and have the actual one at the project root then things work fine.

double font-size

Hi there! =) Which one should it be?

Getting warning about author key being deprecated

With Hugo 0.120.3, I am getting a warning:

> hugo server -D
...
hugo v0.120.3-a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970+extended darwin/arm64 BuildDate=2023-11-01T17:57:00Z VendorInfo=gohugoio

WARN  The author key in site configuration is deprecated. Use params.author.name instead.

Any chance we can update https://1bl4z3r.github.io/hermit-V2/en/posts/explaining-configs/ to match this?

Thanks in advance

Release v1.0.12 breaks builds unless blank assets/scss directory exists in project root

Hi! Thanks for the great theme 😄

The latest v1.0.12 build causes an error to be thrown when the theme is cloned as a submodule of a repository which does not have an assets/scss directory due to the addition of this code:

hermit-V2/assets/scss/style.scss

Lines 9 to 11 in 93f7434

	{{ if (where (readDir "assets/scss") "Name" "userstyles.scss") }}
	@import "userstyles.scss";
	{{ end }}

$ hugo serve
Start building sites … 
hugo v0.111.3+extended linux/amd64 BuildDate=2023-03-16T08:41:31Z VendorInfo=debian:0.111.3-1
Error: Error building site: EXECUTE-AS-TEMPLATE: failed to transform "scss/style.scss" (text/x-scss): template: scss/style.scss:9:14: executing "scss/style.scss" at <readDir "assets/scss">: error calling readDir: failed to read directory "assets/scss": open /home/path/to/repo/assets/scss: no such file or directory
Built in 18 ms

I'm guessing this is down to the fact that although an if is being used, the readDir tries to read the contents of assets/scss before the if is invoked. Maybe there's another if statement that could be nested in here to avoid failing out if the directory doesn't exist.

It's not a showstopping issue, because creating an empty assets/scss directory is enough to make this work as it did before, but it might be one to call out in the README for new users that this directory needs to exist. I only noticed this so easily because the theme previously worked and I was able to see quite quickly from the recent commits what the cause was. I think a user who is newer to the theme might just be puzzled by this one.

Request: `shareSocial` option to copy link to clipboard

Here is what my current share menu looks like (as of 3eabdaf), and it looks great. 🥳

For many share features on other website, a sharing option is supported that copies the page's hyperlink to the clipboard. On Google Chrome's mobile app, this sharing option is called "Copy link".

My request here: add a share option for just copying the page's link to the clipboard

[BUG] - Demo site doesn't have 404 enabled

Describe the bug

The demo site doesn't have custom 404 enabled, e.g., https://1bl4z3r.github.io/hermit-V2/en/about-hugo/s

I don't know why, as I found the theme by default creates a 404.html file.

Recent code changes to `main` branch?

The recent changes have been awesome, I am looking to use them now.

Either:

• I can set my git submodule to use the staging branch
• hermit-V2's main branch can be updated

Do you mind updating the main branch? I think having the example site diverge from the main branch can be confusing to new users

Possibly extra dot in `single-footer.html`

Currently from https://1bl4z3r.github.io/hermit-V2/:

It seems to me there is either:

• A missing middle dot between the name and CC BY-NC
• An extra "middle dot between CC BY-NC and the RSS logo

Do you agree? Imo it's visually imbalanced at the moment