Extending Wowchemy

How can you perform more advanced customization or integrate new third-party services?

Add scripts (JS)

To add a third party script, create a file named custom_js.html in a layouts/partials/ folder at the root of your website. Any HTML code added to this file will be included within your website’s footer.

Whereas for your own local scripts, let’s say that you have a JS file named custom.js. We can place your file in assets/js/ (create the folders within your website root if they don’t exist). Then open your config/_default/params.yaml and set plugins_js: [custom], where custom is your JS filename without its extension.

Custom head

To add custom metadata or scripts to your website’s <head>, create a file named custom_head.html in a layouts/partials/ folder at the root of your website and add your HTML code.

This approach can also be used for adding third party scripts with an async or defer attribute to the site head.

Customize style (CSS)

To personalize Wowchemy, you can choose a colour theme and font set in config/_default/params.yaml.

For further personalization, you can create your own colour theme and font theme.

If advanced style customization is required, CSS code can be written to override or enhance the existing styles:

  1. Create the assets/scss/ folder if it doesn’t exist
  2. Create a file named custom.scss in the assets/scss/ folder
  3. Add your custom CSS code to the file you created and re-run Hugo to view changes

Override a template

Hugo uses a template lookup which enables you to override any of Wowchemy’s files without directly changing them. This can make it easier to update Wowchemy in the future since you do not modify any of Wowchemy’s files directly.

Alternatively, you might wish to:

To override a template in the theme, you simply copy the file you are interested in from the version of the Wowchemy module your site uses and paste it in your site folder using a similar path. To choose your version, select its tag from GitHub’s dropdown master box on the upper left and press enter.

To understand how this works, you should familiarize yourself with template lookup. Finally, when you update Wowchemy, remember to compare your version of the file against Wowchemy’s one, in case you need to propagate any changes across.

For example, say we wish to add some HTML code to the navigation bar. Let’s copy the relevant file wowchemy/layouts/partials/navbar.html to layouts/partials/navbar.html at the root of your site, creating the layouts/partials/ folders if they do not already exist. Now you can add the HTML code you want to your copy of the file, which will override Wowchemy’s version.

Permalinks, or permanent links, are URLs to individual pages and posts on your website. They are permanent web addresses which can be used to link to your content. Using Hugo’s permalinks option these can be easily customized. For example, the blog post URL can be changed to the form yourURL/2016/05/01/my-post-slug by adding the following near the end of your config/_default/config.yaml:

  post: '/:year/:month/:day/:slug'

Where :slug defaults to the filename of the post, excluding the file extension. However, slug may be overridden on a per post basis if desired, simply by setting slug: my-short-post-title in your post preamble.

Example 2: let’s consider changing the URL path of posts from post/ to blog/. First, add the following parameters to your config/_default/config.yaml:

  post: '/blog/:slug'

Then add aliases: [/blog/] to your post archive page at post/_index.md so that it can be accessed from the /blog/ URL.

Theming Custom Integrations

How can you theme your customizations and third-party plugins according to the user’s light/dark mode?

Theming can be performed with styles and/or JS.

Plugins can be themed by creating a custom style (see Style section above) and prefixing dark components with .dark such that you might have:

/* Light component */
.your-class {color: black;}
/* Dark component */
.dark .your-class {color: white;}

Furthermore, Wowchemy v5.0.0+ emits a wcThemeChange event to help support themeable user plugins.

One can add a custom local JS script (see Scripts section above) and listen to the event.

For example, adding the following snippet to a custom JS script referenced in params.yaml outputs the theme change events to the browser console:

document.addEventListener('wcThemeChange', (e) => 
  console.log('isDarkTheme? ' + e.detail.isDarkTheme())