StatnMap Hugo theme
StatnMap theme is issued from hugo-icarus-theme by digitalcraftsman, but I thought visual changes were to big to keep it as a fork. This is a responsive and customizable theme for bloggers and freelancers. It's originally a port of the Icarus theme for Hexo made by Ruipeng Zhang. The theme has been revamped to look like wordpress twenty-fifteen theme. Noteworthy features of this Hugo theme are the integration of a comment-system powered by Disqus, multilingual support and language switch, syntax highlighting and code folding for source code, how-to-cite card and related articles sections on bottom of articles, contact form and optional widgets for the sidebar.
Get the theme
I assume you've Git installed. Inside the folder of your Hugo site run
$ cd themes
$ git clone https://github.com/statnmap/hugo-statnmap-theme.git
You should see a folder called hugo-statnmap-theme
inside the themes
directory that we created a few moments ago. For more information read the official setup guide of Hugo.
Setup
Next, navigate to the exampleSite
folder at themes/hugo-type-theme/exampleSite/
. In order to get your site running, you need to copy config.toml
and all the content of all relevant subfolders such as i18n/en.toml
into the root folders.
To turn the exampleSite
folder in a standalone demo site the themesDir
property has been set to ../..
. This way you can preview this theme by running hugo server
inside exampleSite
folder.
Due to the customized themesDir
path Hugo will fail to find themes if you copied the config.toml
into the root directory of a regular Hugo website. Make sure you comment out the themesDir
property if you use the theme in production.
The config file
Now, let us take a look into the config.toml
. Feel free to play around with the settings.
Comments
The optional comment system is powered by Disqus. Enter your shortname to enable the comment section under your posts.
disqusShortname = ""
Tip: you can disable the comment section for a single page in its frontmatter:
+++
disable_comments = true
+++
Menu
You can also define the items menu entries as you like. First, let us link a post that you've written. We can do this in the frontmatter of the post's content file by setting menu
to main
.
+++
menu = "main"
+++
Furthermore, we can add entries that don't link to posts. Back in the config.toml
you'll find a section for the menus:
[[params.menu]]
before = true
label = "Home"
link = "/"
Define a label and enter the URL to resource you want to link. With before
you can decide whether the link should appear before or after all linked posts in the menu. Therefore, Home
appears before the linked post.
Sidebars
In order to use the full width of the website you can disable the profile on the left and / or the widgets on the right for a single page in the frontmatter:
+++
disable_profile = true
disable_widgets = true
+++
Tell me who you are
This theme also provides a profile section on the left. Add your social network accounts to the profile section on the left by entering your username under social
. The links to your account will be create automatically.
Widgets
Beside the profile section you can add widgets on the right sidebar. The following widgets are available:
- recent articles
- category list
- tag list
- tag cloud
You can deactivate them under params.widgets
:
[params.widgets]
recent_articles = false
categories = true
tags = true
tag_cloud = true
Date line
The date line includes: post date, # of words, approximate reading, time tags and categories. However, if you want certain pages to omit the date line, simply put nodateline = true
in the front matter for that page.
Disable Previous / next article links
To disable the inclusion of a previous/next article link at the bottom of the page, add noprevnext = true
to the front matter. This feature, along with nodateline
can be used to create standalone pages that are less "blog-like"
Multilingual
You don't blog in English and you want to translate the theme into different language? No problem. Take a look in the i18n
folder and you'll find a file en.toml
. It contains all strings related to the theme. Copy this file, change the name so that it reflects the translation language (like fr.toml
) and modify the strings needed.
A language switcher is also available with multilingual website activated. You can add png images of flags named 'lang.png' in 'static/flags' folder, for new languages other than English and French.
The config.toml
file in exampleSite
proposes menus for a second language (French). However, as no posts, itemized or contacts are saved with .fr.md
extension in this exampleSite, menu items may redirect to the 404 not found
page.
If you only have one language for your website, you can remove every Languages
, Languages.en
and Languages.fr
occurrences. Simple [menu.main]
have to be used instead.
Credit: statnmap
Contact form
Since this page will be static, you can use formspree.io as proxy to send the actual email. Each month, visitors can send you up to one thousand emails without incurring extra charges. Begin the setup by following the steps below:
- Enter your email address under ‘emailservice’ in contact/index.md file
- Upload the generated site to your server
- Send a dummy email yourself to confirm your account
- Click the confirm link in the email from formspree.io
- You’re done. Happy mailing!
Credit: statnmap
Linking thumbnails
After creating a new post you can define a banner by entering the relative path to the image.
banner = "banners/placeholder.png"
Credit: digitalcraftsman
A thumbnail will be used for the recent_articles list in the sidebar as well as in the normal list of articles. If you want a specific thumbnail instead of the banner croped, you can define it by entering the relative path to the thumbnail.
thumbnail = "banners/thumbnail.png"
This way you can store them either next to the content file or in the static
folder.
Credit: statnmap
Mathematical equations
Mathematical equations in form of LaTeX or MathML code can be rendered with the support of MathJax. MathML works out of the box. If you're using LaTeX you need to wrap your equation with $$
.
You can also print formulas inline. In this case wrap the formula only once with $
.
If you don't need equations, you can disable MathJax but putting disable_mathjax = true
in your config.toml. This will prevent clients from unnecessarily downloading the MathJax library.
MathJax CDN and versions can be modified in the config.toml
file:
MathJaxCDN = "//cdn.bootcss.com"
MathJaxVersion = "2.7.1"
Syntax highlighting
Syntax highlighting for code is allowed with highlight.js
. This can be disabled in the config.toml
. Version, additional languages, CDN and theme can also be modified.
disable_highlight = false
highlightjsVersion = "9.11.0"
highlightjsCDN = "//cdn.bootcss.com"
highlightjsLang = ["r", "yaml"]
highlightjsTheme = "github"
Credit: yihui
Code folding
Code folding is enabled by default with disable_codefolding = false
in parameters of the config
file. It uses somes javascript libraries of bootstrap. Code folding (multilingual) buttons only appear when there is code in the document rendered from Rmd
in blogdown. disable_codefolding
can also be used in each article config header. Similarly, you can define if code blocks are shown or hidden by default using codefolding_show = "hide"
in the config file or in each article config.
The list of <pre>
blocks on which to apply code folding is defined in the config
file: codeblocks = ["pre.sourceCode", "pre.r", "pre.python"]
Credit: statnmap
Sticky list pages
A special kind of posts list is implemented. This allows to show the first article completely and the other articles as a list with summaries. For that, we use the implemented template list_first_plain_sticky.html
in partial
. You can use it in two ways:
-
With Taxonomy This is implemented in the
exampleSite
.- Create a new taxonomy like 'sticky':
[Taxonomies] tag = "tags" category = "categories" sticky = "stickies"
- Create a folder
layout
>taxonomy
- Create a html file named
sticky.html
with this code:
{{ define "main" }} {{ if isset .Site.Taxonomies "sticky" }} {{ partial "list_first_plain_sticky" . }} {{ end }} {{ end }}
- Add taxonomy
stickies
in a post or a page. The newest page or the page withweight = 1
will be shown entirely before the other of the same taxonomy (that will only show a summary). In the exampleSite, pages insticky_pages
have this taxonomy.
-
With special pages
- Create a folder
layout
>sticky_pages
for instance - Create a html file named
list.html
with this code:
{{ define "main" }} {{ partial "list_first_plain_sticky" . }} {{ end }}
- Create a folder
content
>sticky_pages
(This is done in theexampleSite
) - Add a page. The newest page or the page with
weight = 1
will be shown entirely before the other of the same taxonomy (that will only show a summary)
- Create a folder