Extending Wowchemy

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

Hooks

The Hugo hooks system enables you to easily inject your own code into parts of a site for more advanced customization. No need to edit or override any of the theme’s files!

The following hooks are supported (as of v5.6-dev):

head-start
head-end
body-end
footer-start
toc-start (for the right sidebar table of contents only)
toc-end (for the right sidebar table of contents only)

To inject your code into one of the above places, create a file at layouts/partials/hooks/<hook>/<your-filename>.html, replacing <hook> with one of the hook names above and <your-filename> with any name, such as custom. You’ll need to create these new folders relative to the root of your site.

For example, to inject your code into the site head, you can create a file at layouts/partials/hooks/head-end/custom.html.

You can have multiple files in each hook folder, with Hugo determining the order which they are rendered in.

Add scripts (JS)

How can I add custom Javascript to my site, such as a third-party analytics script?

Create a file at layouts/partials/hooks/body-end/custom.html and paste your Javascript <script>...</script> within it.

For older sites prior to v5.6, create a file at layouts/partials/custom_js.html instead.

Custom head

How can I add custom metadata to my website’s <head> tag?

Create a file at layouts/partials/hooks/head-end/custom.html and paste your HTML tags within it.

For older sites prior to v5.6, create a file at layouts/partials/custom_head.html instead.

Tip: 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:

Create the assets/scss/ folder if it doesn’t exist
Create a file named custom.scss in the assets/scss/ folder
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

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:

permalinks:
  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:

permalinks:
  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())
);