The Hugo Zen theme

Zen theme strives to be as clean and standard compliant as possible with some neat features. A solid base for your custom Hugo theme.

It uses HTML5 with a modern CSS grid and flex layout. Recent versions of all the mayor browsers support it, see Can I use css grid.

Sass is processed with Hugo pipes that was added in Hugo 0.46. To make using npm optional I have added the stylesheets from the excellent sass plugin typey to the theme directly.

This is originally a port of the Zen theme by JohnAlbin, a very popular base theme for Drupal.

View Demo Download Source

Features

A mobile menu
Analytics with Matamo (Piwik)
Automatic linting of css and js
Contact form (PHP)
CSS grid and flex for layout
Gulp.js (only for sass/js lint)
HTML5
Hugo Pipes for js and sass
jQuery 3
Micro.blog
Minify css
Meta tags and JSON-LD
Multilingual (i18n)
Normalize CSS
Responsive design
RSS and JSON feeds with full content
Search with DuckDuckGo
Sub theme support (Theme Components)
Umbrella JS 3 (tiny jQuery replacement, 2.5kB when gzipped)

Performance

Performance should be excellent.

Minimal and compliant HTML5
Styles 17,7 kB (4,3 kB when gzipped)
JavaScript 8,4 kB (2,7 kB when gzipped)
All scripts loaded in head with "defer"
Optimised for HTTP/2

Some performance tools will complain about to many files (js and css files are not concatenated) but with HTTP/2 that can be ignored.

Sites using the Hugo Zen theme

On the large screen

screenshot

On the small screen

screenshot

The mobile menu

screenshot

Installation

$ cd themes
$ git clone https://github.com/frjo/hugo-theme-zen.git zen

Hugo - Installing Hugo

Customise layouts

To customise a layout included in the zen theme, copy it to the root layout directory and edit it there. Make sure to maintain the directory structure inside the layouts directory.

Add any new layouts to the root layout directory as well. This way they will not be overwritten when updating the theme.

Customise styles and scripts

Styles and scripts are processed with Hugo pipes that was added in Hugo 0.46.

To customise a js or sass file, copy it to the root assets directory and edit it there. Make sure to maintain the directory structure inside the assets/sass directory.

The default styles in "_zen.scss" are boring but functional. You can easily overide them completely by placing an empty file named "_zen.scss" in root assets/sass directory.

By default the sass files are built for production, compressed with fingerprint. By setting the Hugo enviroment variable to "dev" they will instead be nested with sourcemaps.

§ hugo serve watch --environment=dev

config.yaml example

All the "params" are optional.

baseurl: "https://example.org/"
title: "SiteTitle"
theme: "zen"

params:
  contact: "[email protected]"
  copyright: "This site is licensed under a 
              (https://creativecommons.org/licenses/by-sa/4.0/)."
              [Creative Commons Attribution-ShareAlike 4.0 International License]
  dateformat: ""            # Set the date format, default to "2 January, 2006"
  description: ""           # Set site description, used in meta tags and JSON-LD
  favicon: ""               # Relative path to favicon in json feed, no leading slash.
  feedlinks: true           # Show feed links in the footer.
  footer: "A [example.org](https://example.org/) production."
  icon: ""                  # Relative path to icon in json feed, no leading slash.
  image: ""                 # Relative path to site image in JSON-LD, no leading slash.
  imageMaxWidth: ""         # Max width for images added via figure shortcode.
  jquery: true              # Add jQuery
  languageDir: ""           # Set ltr or rtl, defaults to ltr.
  logo: false               # Turn off the logo.
  microUsername: ""         # Your micro.blog username.
  mobileMenu: true          # Turn on a mobile menu on small screens.
  piwikSiteId:              # Matamo site id
  piwikTrackerUrl: ""       # Matamo url, schemaless and no slash on end (example.com/matamo).
  poweredby: true           # Show powered by hugo in footer
  search: true              # Site search with DuckDuckGo.
  searchSize: 20            # Search field size, default 20.
  sidebar: true             # Show a sidebar to the right
  submitted: true           # Show author and date information for a post.

Multilingual

English and Swedish translations are included and you can easily add more to the i18n site directory.

A language selector will be included on sites with more than one language. Add a LanguageName parameter to your language configuration, this is what will be displayed in the selector.

The language selector will link to a translation of the current page if it exist and to the front page if it does not.

languages:
  sv:
    weight: 1
    params:
      LanguageName: "Svenska"
  en:
    weight: 2
    params:
      LanguageName: "English"

Contact form

If your server support php with the mail() command (very common) you can use the included contact form feature to get a contact form for your site.

Copy the file themes/zen/php/contact.php.example to static/php/contact.php.
Edit the contact.php file so it has your own e-mail address. You may also change the mail subject prefix.
Add the shortcode {{< contact >}} to a page. Also set contactform: true in the front matter for that page so the contact.js file gets loaded.

If you have a SPF record for your domain, make sure the web server is listed or other mail server may mark the mail as spam.

Two types of spam protection is implemented. The form can only be posted after the user have moved the mouse or pressed the tab or enter key. The form have a "honypot" field that is invisible to humans but not to most spam boots. If that field is filled in the mail will not be sent.

Form validation is handeld by HTML5 and there is some CSS to make it look nice.

Javascript is used for spam protection and to display error/success messages.

Dates

If "lastmod" is set in the frontmatter on a post that value will be used in the "submitted" section. If not "date" is used.

With "lastmod" set a date section will also appear at the bottom of post telling the reader the created and modification dates.

Shortcodes

Contact

Insert a html5 contact form, see more above.

{{< contact >}}

Figure

Zen comes with a improved version of the built in "figure" shortcut.

You can set a max width for images with parameter "imageMaxWidth".
If width and height is not set the real dimensions of the image will be used.
If only width or height is set the other value will be proportionally calculated.

Clear

Break float.

{{< figure src="/images/image.jpg" class="right" >}}

blablabla # Displayed left of the image.

{{< clear >}}

blablabla # Displayed below of the image.

Wrapper

A simple, but useful, shortcode to wrap content in a div with a class. The content will be run through "markdownify".

{{< wrapper class-name-you-want markdown >}}
The **content** that should be wrapped.

Some more content.
{{< /wrapper >}}

This will produce:

<div class="class-name-you-want">
<p>The <strong>content</strong> that should be wrapped.</p>

<p>Some more content.</p>
</div>

If the content should be left untouched add "nomarkdown" after the class name.

{{< wrapper class-name-you-want nomarkdown >}}
The **content** that should be wrapped.

Some more content.
{{< /wrapper >}}

This will produce:

<div class="class-name-you-want">
The **content** that should be wrapped. Some more content.
</div>

Choose between using jQuery or Umbrella JS

Umbrella JS is always added and it's used for all theme JavaScript. To add jQuery, set the related parameter to true in the configuration file or in the front matter of specific pages. No problem having both libraries loaded on the same page.

This is the way I construct my JavaScript files.

Umbrella JS:

(function ($) {

  'use strict';

  // Add your code here.
  $('html').removeClass('nojs').addClass('js');

})(u);

jQuery:

(function ($) {

  'use strict';

  // Add your code here.
  $('html').removeClass('nojs').addClass('js');

})(jQuery);

Use Gulp to lint Sass and JavaScript

Lint your Sass using sass-lint.
Lint your JavaScript using eslint.
Will lint files in the theme as well as the root assets directory.
Watch all of your files as you develop and re-build everything on the fly.

Set up your front-end development build tools:

Install Node.js and npm, the Node.js package manager.

Detailed instructions are available on the "npm quick start guide":
https://github.com/kss-node/kss-node/wiki/npm-quick-start-guide
The package.json file in your new sub-theme contains the versions of all the
Node.js software you need. To install them run:
```
 npm install
```
Install the gulp-cli tool globally. Normally, installing a Node.js globally
is not recommended, which is why both Gulp and Grunt have created wrapper
commands that will allow you to run "gulp" or "grunt" from anywhere, while
using the local version of gulp or grunt that is installed in your project.
To install gulp's global wrapper, run:
```
 npm install -g gulp-cli
```
The default gulp task will lint your Sass and JavaScript.
To run the default gulp task, type:
```
 gulp
```
To watch all your files as you develop, type:
```
 gulp watch
```

Create a zen subtheme

Since Hugo 0.42 there is sub them support via Theme Components. A nice feature if you want to extend an existing theme, like zen.

If all you want is customise layouts, styles and scripts for a site it's easier to copy the needed files to the root layout and assets directories and edit them there. See instructions above.

The included "create_sub_theme.sh" script makes it easy to get started on a sub theme. Navigate to the theme directory where you have placed the zen base theme and run the script like this.

$ ./zen/create_sub_theme.sh

Enter a name for your sub theme when asked for. In the site config file add your sub theme name first and "zen" after it. Hugo will now first look in the sub theme for files and if they are not there look in the zen base theme.

A port of the Drupal zen base theme with css-grid and Hugo pipes support

The Hugo Zen theme

Features

Performance

Sites using the Hugo Zen theme

On the large screen

On the small screen

The mobile menu

Installation

Customise layouts

Customise styles and scripts

config.yaml example

Multilingual

Contact form

Dates

Shortcodes

Contact

Figure

Clear

Wrapper

Choose between using jQuery or Umbrella JS

Use Gulp to lint Sass and JavaScript

Create a zen subtheme

GitHub

Hugo

A theme for a conference website

Minimalistic and Responsive blog theme for hugo

Aditu Dark Theme HUGO Theme

A minimalist, highly-versatile theme for Hugo

Hally Hugo Theme

A simple retro theme for Hugo

Aditu Dark Theme HUGO Theme

A minimalist, highly-versatile theme for Hugo

Hally Hugo Theme

A simple retro theme for Hugo

The Hugo Zen theme

Features

Performance

Sites using the Hugo Zen theme

On the large screen

On the small screen

The mobile menu

Installation

Customise layouts

Customise styles and scripts

config.yaml example

Multilingual

Contact form

Dates

Shortcodes

Contact

Figure

Clear

Wrapper

Choose between using jQuery or Umbrella JS

Use Gulp to lint Sass and JavaScript

Create a zen subtheme

GitHub

A theme for a conference website

Minimalistic and Responsive blog theme for hugo

You might also like...

You might also like...