Hugo - Theme Plugin

Now that we have all the critical components ready, it's time to move up to one of the Hugo's unique selling point: theme module. Hugo from architectural point of view, learn from the cons of its competitor, develops a method to allow user to apply styles, settings etc. in modular manner. This way, user can switch between design easily without interfering with current configurations, posts and contents.

Based on specification, you can modularize a list of items:

  • archetypes
  • layouts
  • static
  • i18n
  • data
  • config.toml
  • and anything else (with instruction given)


What you need to do is to move the modular items into the corresponding theme folder and Hugo will look for it automatically. How Hugo seeks files is by this sequence:

  1. Search local directory for the file
  2. If #1 is not found, Search the specified theme directory


We can now see that files, sharing the same directory pattern as the local version, acts as a secondary module. If you want customization, you can change it in your local directory. Let's test this out!

Objectives

  1. Create a vanilla theme and move all files that can be templates into the theme module.
Hugo - themes - Create New Theme

Create the Theme Directory

To create the theme module, Hugo actually packs with a single command to create the necessary to create the theme. Let's create our vanilla theme.

$ hugo new theme vanilla
Hugo - Themes - Transferring Components

Transfer Layout to Themes

Now, let's move the layouts into the themes. Layouts and static files are template designs components that can be used across different Hugo contents across repositories. You can do it by:

$ cp -r layouts/* themes/vanilla/layouts/.
$ rm -rf layouts/*

Tip: use ls to check before performing rm -rf.

Hugo - Themes - Activate and Use Theme

Activate Theme

If you restart your server, you'll realize that your existing pages are not longer available. This is because we haven't instruct Hugo to use a theme. To do so, let's edit our local config.toml and add the following configuration

theme = ["vanilla"]

Also, you must remove the index.html from the vanilla theme since we're using content/_index.md as home page.

$ rm themes/vanilla/layouts/index.html

Once you're done, restart your server and you should see your contents should not change. Congratulations, you had successfully shifted the layouts to your theme module.

NOTE: the keyword inside the "theme" array MUST match the directory name in the themes directory. Example: vanilla for themes/vanilla. Otherwise, Hugo can't find the correct theme module.

NOTE: you can use multiple non-conflicting theme modules at a time.

Continue to Design Your Themes

You can continue to shift template files from your local repository to the theme modules. Once you're happy with it, create a git repository inside the vanilla theme directory. Moving forward, you can now reuse vanilla theme in any other Hugo repository. Just git clone it inside the themes directory, configure it to use the theme and you're all set!

Congratulations! You had completed the basic of Hugo!