Hugo Themes
Hugo ReFresh
A multi-page, clean and responsive theme. Multilingual supported.
- Author: Roberto Jordaney
- GitHub Stars: 116
- Updated: 2024-07-29
- License: MIT
- Tags: Blog Light Multilingual Personal Responsive
The ReFresh theme for Hugo
ReFresh is a theme for the Hugo static site generator inspired from the awesome Fresh theme (below you can find the list of changes to the original theme).
You can find a live demo of the ReFresh theme in my personal website.
This theme is intended for personal website and blog. If you’d like to extend the theme to include other functionalities submit a pull request.
Getting started
To create a new site using Hugo ReFresh:
# Create site and cd into it
hugo new site my-site && cd my-site
# Clone the ReFresh theme into the themes folder
git init
git submodule add https://github.com/PippoRJ/hugo-refresh.git themes/hugo-refresh
# Remove the default config
rm config.toml
# Fetch the example config
curl -O https://raw.githubusercontent.com/PippoRJ/hugo-refresh/master/exampleSite/config.yaml
# Run the site locally
hugo server -D
# Open the site in your browser
open http://localhost:1313
To run the Example Site using Hugo ReFresh:
# Create site and cd into it
hugo new site my-site && cd my-site
# Clone the ReFresh theme into the themes folder
git init
git submodule add https://github.com/PippoRJ/hugo-refresh themes/hugo-refresh
# Remove the default config
rm config.toml
# Copy the Example site content and configuration in my-site
cp -R themes/hugo-refresh/exampleSite/* ./
# Open the site in your browser
hugo server -D
Troubleshooting
If you see error: failed to transform resource: TOCSS: failed to transform "style.sass"
when attempting to run your hugo server
, make sure you have the extended version of Hugo installed:
# On Ubuntu:
snap refresh hugo --channel=extended
Statistics counter
You can enter your Google / Yandex / etc statistic counter code into the layouts/partials/counter.html
. Code will be generated right after open <body>
tag.
Custom HEAD
If you want to include custom scripts at the end of the HEAD
section, create a file in layouts/partials/custom_head.html
and add your content there.
Customizing your page
There are different configuration options for Hugo ReFresh including options for: the navbar, the sidebar, the homepage, fonts, colours landing, stats counters and images.
Read the comments in the config.yaml
file to know more.
The images specified in the config.yaml
file need to be placed in the directory specified by the assetDir
option in the config file.
E.g.: set assetDir: "static"
to the set the default folder the static
folder of your site.
List of shortcodes you can use in your articles with description:
A live example of these shortcodes can be found here.
title1.html, title2.html, title3.html, title4.html, title5.html, title6.html
Usage example:
{{< title1 "My awesome title" "my-title-id">}}
The first parameter is the title of the shortcode (in this example is “My awesome title”).
The second paramter is the ID of the shortcode (in this example is “my-title-id”).
It can be used in links to the same page as:
[link to the title](#my-title-id)
subtitle1.html, subtitle2.html, subtitle3.html, subtitle4.html, subtitle5.html, subtitle6.html
Usage example:
{{< subtitle1 "My awesome subtitle" "my-subtitle-id">}}
The first parameter is the title of the shortcode (in this example is “My awesome subtitle”).
The second paramter is the ID of the shortcode (in this example is “my-subtitle-id”).
It can be used in links to the same page as:
[link to the subtitle](#my-subtitle-id)
code.html
This shortcode builds a centred page that is two-third of the full size of the page.
Usage example:
{{< code language="shell" >}}
$ sudo bash -c 'echo 0 > /proc/sys/kernel/randomize_va_space'
{{< /code >}}
This shortcode has 2 parameters:
line-numbers to hide or show the line numbers. The default is true, for single line code the number is never shown.
language is used to highlight the syntax of the code properly
codeWide.html
This shortcode builds a centred page that is as wide as the full size of the page.
Usage example:
{{< codeWide language="shell" >}}
$ dmesg | tail
......
[13401.299114] overflow64[16566]: segfault at 616161616161 ip 0000616161616161 sp 00007fffffffddb0 error 14 in libc-2.27.so[7ffff79e4000+1e7000]
{{< /codeWide >}}
This shortcode has 2 parameters:
line-numbers to hide or show the line numbers. The default is true, for single line code the number is never shown.
language is used to highlight the syntax of the code properly
container.html
This shortcode builds a centred page that is as wide as the two third of the size of the page. The content of the shortcode will pass through the markdown processor.
Usage example:
{{< container "container-id" >}}
{{< /container >}}
This shortcode has an optional parameter to give an ID to the html div
.
containerWide.html
This shortcode builds a centred page that is as wide as the size of the page. The content of the shortcode will pass through the markdown processor.
Usage example:
{{< containerWide "container-wide-id" >}}
{{< /containerWide >}}
This shortcode has an optional parameter to give an ID to the html div
.
figure.html
This shortcode resize an image that with the width and/or height that you specify
Usage example:
{{< figure src="images/the_stack.png" width="700" >}}
{{< figure src="images/the_stack.png" height="700" >}}
The parameter src is the location of the image relative to the location of the file where the shortcode has been used.
The parameter width is the width of the image.
The parameter height is the height of the image.
The parameter caption is the caption of the image.
The parameter alt is the alt property of the image.
twoFigure.html
This shortcode shows 2 images one next to the other with the possibility to resize them.
Usage example:
{{< twoFigure src1="images/overflow_1.png" width1="700" src2="images/overflow_2.png" width2="700" >}}
The parameter src1 is the location of the right image relative to the location of the file where the shortcode has been used.
The parameter width1 is the width of the right image.
The parameter height1 is the height of the right image.
The parameter caption1 is the caption of the right image.
The parameter alt1 is the alt property of the right image.
The parameter src2 is the location of the left image relative to the location of the file where the shortcode has been used.
The parameter width2 is the width of the left image.
The parameter height2 is the height of the left image.
The parameter caption2 is the caption of the left image.
The parameter alt2 is the alt property of the left image.
With a small screen these images will be shown one on top of the other.
See example of use here
twoVideos.html
This shortcode shows 2 YouTube videos one next to the other.
Usage example:
{{% twoVideos id2="pKRzfdIJUZE" id1="Ncv2KmhVgyU" autoplay1=true ratio1="4:3" ratio2="16:9" %}}
The parameter id1 is the ID of the left video
The parameter id2 is the ID of the right video
The parameter autoplay1 is used to start the video on the left (the video will start on mute). Set it to “true” to activate autoplay.
The parameter autoplay2 is used to start the video on the left (the video will start on mute). Set it to “true” to activate autoplay.
The parameter ratio1 is used to specify the the ratio of the video on the left. It can be either “16:9” or “4:3”. The default is “16:9”.
The parameter ratio2 is used to specify the the ratio of the video on the right. It can be either “16:9” or “4:3”. The default is “16:9”.
With a small screen these videos will be shown one on top of the other.
book.html
Usage example:
{{< book title="Title Awesome" authors="Awesome author" image="images/cover.jpg" size="300x">}}
The parameter title is the title of the book.
The parameter authors contains the authors of the book.
The parameter image is the cover of the book.
The parameter size is used to specify the size of the book in pixel “width” x “height”.
E.g.: “300x” means 300px of width.
E.g.: “x300” means 300px of height.
See example of use here
exercise.html
Usage example:
{{< exercise >}}
Text of the exercise.
{{< /exercise >}}
This shortcode has no parameters.
See example of use here
tabsCode.html
Usage example:
{{< tabsCode
file1="/content/code_exercises/staircase_n_steps/code/solution_python.md" language1="python" title1="Python" icon1="python"
file2="/content/code_exercises/staircase_n_steps/code/solution_c.md" language1="c" title2="C" icon2="c"
file3="/content/code_exercises/staircase_n_steps/code/solution_java.md" language1="java" title3="Java" icon3="java"
>}}
The parameter file1 is the name of the code file to be displayed in the first tab.
The path needs to start from the content
folder.
The parameter language1 is used to highlight the syntax of the code properly.
The parameter title1 is the title of the first tab.
The parameter icon1 is the icon to be shown at the right of the title, it is an optional parameter. See the partial code icon.html
for the available icons.
There are 6 tabs supported at this moment
the files parameters are file1, file2, file3, file4, file5, file6
the titles parameters are title1, title2, title3, title4, title5, title6
the languages parameters are language1, language2, language3, language4, language5, language6
the icons parameters are icon1, icon2, icon3, icon4, icon5, icon6
See example of use here
tabs.html
Usage example:
{{< tabs
file1="/content/exercises/article1/comments/my_comments.md" title1="My Ideas"
file2="/content/exercises/article1/comments/your_comments.md" title2="Your Ideas"
file3="/content/exercises/article1/comments/her_comments.md" title3="Her Ideas"
>}}
The content of the files (file1, file2 …) are passed through the markdown processor, so you can use markdown in these files.
The parameter file1 is the name of the code file to be displayed in the first tab.
The path needs to start from the content
folder.
The parameter title1 is the title of the first tab.
The parameter icon1 is the icon to be shown at the right of the title, it is an optional parameter. See the partial code icon.html
for the available icons.
There are 6 tabs supported at this moment
the files parameters are file1, file2, file3, file4, file5, file6
the titles parameters are title1, title2, title3, title4, title5, title6
the icons parameters are icon1, icon2, icon3, icon4, icon5, icon6
codeInLine.html
Usage example:
{{< codeInline >}}sudo echo 0 > /proc/sys/kernel/randomize_va_space{{< /codeInline >}}
This shortcode has 2 parameters:
language is used to highlight the syntax of the code properly
id to set a id of the html
code
element
See an example of usage here
messageBlue.html, messageDark.html, messageGreen.html, messageRed.html, messageYellow.html
notificationBlue.html, notificationGreen.html, notificationRed.html, notificationYellow.html
siteBlue.html, siteGreen.html, siteLightgreen.html, siteRed.html, siteYellow.html
Usage example:
{{< siteLightgreen "Web" "https://www.example.com" >}}
<p>Description of the website.</p>
{{< /siteLightgreen >}}
The first parameter will appear in the right coloured part of the shortcode.
The second parameter will appear in the middle part of the shortcode.
See example of usage here
Customization options for a regular page
These are the options that you can define is the front matter of a regular page:
---
title: "My Awesome Title"
date: 2019-06-03T21:51:13+01:00
draft: false
hideLastModified: true
summaryImage: "images/system.jpg"
keepImageRatio: true
tags: ["Tag1", "tag2", "tag 3"]
summary: "This is a custom summary for my article"
showInMenu: true
---
summaryImage
: it is used to specify the image to be used in the summarykeepImageRatio
: it is used to force the aspect ratio of the image to be kept. The default value is false.summary
: it is used to specify the summary of an article instead of taking it from the article itself.hideLastModified
: it is used to hide the the timestamp added at the end of the article.showInMenu
: it is used to show the article in the top right menu.tags
: it is the list of tags for the article; they will be used to build the left sidebar.
To avoid path problems when specifying the summaryImage
, it is recommended to define a regular page as a leaf bundle. The example above will result in:
* my_awesome_title (folder)
* index.md (file)
* images (folder)
* system.jpg (file)
Multilanguage support
To chose the default language you need to set the DefaultContentLanguage
setting in the config.yaml
file.
(You can also have multiple languages at the same time, see exampleSite/config.yaml
for an example.)
The language supported are:
English
Spanish
French
Italian
Russian
Chinese
Polish
German
Portuguese
If you want to add a missing language please submit a feature request.
List of modifications from the original theme
Big modification: The ReFresh theme is transformed from single page template to multipage.
Addition: Added multilanguage support.
Big extension: The left side menu shows tags and number of occurrences dynamically generated based on the content of the pages (not from a list in the config file like in the original theme).
Addition: The theme images change colour accordingly to the main colour theme (i.e.: are now processed with
resources.ExecuteAsTemplate
and the colour is written to the resulting SVG image).Addition: The list and terms types of pages contain a list of the post summaries.
Addition: The images used to build the summaries can be resized to allow better usage of the bandwidth.
Addition: The js and css files can be minified (with a configurable option on the
config.yaml
).Big extension: The menu is automatically built following the structure of the
content
folder (not from a list in the config file like in the original theme). Two levels are allowed at the moment.Suppression: The
navbar-burger
used in the original theme’s menu is removed (it was displayed when the page was resized).Boost: The
.sass
files are now processed withresources.ExecuteAsTemplate
so that it is possible to use variables from theconfig.yaml
.Boost: Options in the
config.yaml
are added to configure the font-family for the navbar, sidebar and content of the a page.Boost: Bulma (the css framework the theme is based on) is now updated to version 0.7.5 because in the new version the class content has a separate style to allow modification that will impact only the contents of the posts.
Extension: highlight.js was added to better highlight the code sections of the posts. I chose the style monokai-sublime.
Extension: highlightjs-line-number.js was added to have the line number at the beginning of each line of code in a code sections of a post.
Extension: A minimal version of MathJax was added to allow LaTeX style mathematical expressions to be placed in the site.
Boosts: Several other options are added to personalise the content of a post.
Extension: A shortcode is added to resize the images and save bandwidth in a post content.
Extension: A shortcode is added to show multiple tabs.
Extension: Four shortcodes are added to show code: inline, in page, in page wide, in tabs.
Boost: The favicon is processed with
resources.ExecuteAsTemplate
to follow the main colour of the page.Extension: Added Open Graph meta tags to each post for easy-sharing on social media sites.
Big Extension: All the js and css files are loaded locally, i.e., not loaded from third party sites.