Customization

Getting started? Wowchemy has a collection of beautiful templates for you to choose from.

Want to personalize the template? No problem, a Wowchemy template is fully customizable. In fact, you can change so many elements, it would be difficult to find the original template it was made from.

This page explains some common site customizations. You might also be interested in customizing the homepage.

Check out the Guides for more customization options such as getting your own domain name, adding analytics, and interacting with comments.

Color Themes

Wowchemy comes bundled with a variety of popular themes built-in including:

To choose a theme, set the theme option in config/_default/params.toml.

Alternatively, you can create your own theme.

Fonts

Your theme comes with a font set to style your titles and text, but you may choose to override it by specifying one of the following built-in font sets or creating your own font set:

• Minimal (modern)
• Classic (original Academic v1 style)
• Rose (traditional serif)
• Mr Robot (futuristic)
• Native: use device fonts for maximum performance

To choose a font set, set the font option in config/_default/params.toml.

Font Sizes

The font size can be changed all the way from extra small to extra large using the font_size option in config/_default/params.toml.

Community Themes

In this section, we will curate themes submitted by users. To create your own theme and request it to be added to this section, follow these steps:

• Follow the guide to create a new theme
• Upload your theme file to a new Github repository
• Reach out to us with the repository link in the Contributing channel in the community Discord

Custom theme

Both the colour theme and font set can be customized.

To customize a color theme:

1. Copy a color theme such as minimal.toml to data/themes/my_theme.toml at the root of your site, creating the data/themes/ folders if they do not already exist. Note: avoid using spaces in filenames.
2. Adjust the colors within your theme file using HTML color codes
3. Tell Wowchemy to use your new theme by setting theme = "my_theme" in config/_default/params.toml

Custom font

To customize the font set:

1. Copy a font set such as minimal.toml to data/fonts/my_font_set.toml at the root of your site, creating the data/fonts/ folders if they do not already exist. Note: avoid using spaces in filenames.
2. Adjust the font family, choosing from the library of Google Fonts if you wish - refer to the Google Font guide below
3. Tell Wowchemy to use your new font set by setting font = "my_font_set" in config/_default/params.toml

To select a free web-font available from Google Fonts:

1. Visit Google Fonts
2. Click on each font you wish to use
3. For each font, click + Select this style for each style you wish to use
4. Click on the icon at the top right (View your selected families) to open the dialog box on the right
5. Click on Embed
6. Under <link>, copy the part of the URL starting from family= to &display=swap... (not included) and paste it as the google_fonts option in your new font theme
   • For example, if Google gives you <link href="https://fonts.googleapis.com/css2?family=B612+Mono&family=Open+Sans&display=swap" rel="stylesheet">, set google_fonts = "family=B612+Mono&family=Open+Sans"
7. Under CSS rules to specify families in Google Font’s dialog, copy the font name and paste it as one of the fonts in your font theme
   • For example, given font-family: 'B612 Mono', monospace;, copy B612 Mono

Change font size

You can modify the font size all the way from extra small to extra large using the font_size option in config/_default/params.toml.

Share your theme

If you create your own theme, consider giving it a unique name and sharing your new theme or font set with the community or following the guide below so that it can be considered for curation.

Website icon

Are you looking to customize the desktop and mobile icon which appears in your site’s Progressive Web App (PWA) and web browser tab?

Save your icon as a square 512x512 pixel image named icon.png and place the image in your root assets/images/ folder, creating the assets and images folders if they don’t already exist.

Note that the icon might also be referred to as a favicon.

Custom footer

Add your own message to the footer of a site using the copyright text field in config/_default/config.toml.

Optionally, you can choose a Creative Commons copyright license in config/_default/params.toml:

copyright_license = {enable = false, allow_derivatives = false, share_alike = true, allow_commercial = false, notice = "Except as otherwise noted, this work is licensed under {license}, and code samples are licensed under the MIT License."}

A copyright_license can also be displayed on a per page basis by adding the option directly to a page’s front matter.

Hide Published With Wowchemy

If you would like to hide the Published with Wowchemy notice, please give back and continue supporting in another way by sponsoring. The notice can be automatically removed whilst sponsoring on an appropriate tier.

To help us develop this free software sustainably under the open source license, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship.

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 (not in the themes folder). 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.toml and set plugins_js = ["custom"], where custom is your JS filename without its extension.

Page Sharer

The Page Sharer enables you to grow your audience by engaging your visitors to share pages on your site with others. Visitors can share your pages via email, Twitter, Facebook, LinkedIn, WhatsApp, Weibo, and many more!

To enable the Page Sharer, set sharing to true in your config/_default/params.toml. Alternatively, it can be enabled or disabled on a per page basis using share in your page front matter.

To customize the Page Sharer, edit data/page_sharer.toml. If you don’t already have this file in your site, update to Wowchemy v4.4+ (if necessary) and copy the page_sharer.toml file to data/page_sharer.toml.

Select your social networks

To enable or disable a button, set its enable option to true or false.

Reorder your social networks

To reorder buttons, move the [[buttons]] instances to your preferred order.

Add a new social network

We’ve already included some of the most popular networks, but further networks can easily be added. To add a button for a new social network, duplicate a [[buttons]] instance and edit its properties. Choose an icon, and give it a title and a one-word, lowercase id. Once you have the sharing URL for the new social network, paste it into the url field, substituting the title of the page to share with {title} and page URL with {url}.

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 (not in the themes folder) 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.

NOTE: Prior to v4.4.0-dev, head_custom.html is used rather than custom_head.html.

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.toml:

[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.toml:

[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.

Customize style (CSS)

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

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
3. Add your custom CSS code to the file you created and re-run Hugo to view changes

Note: prior to v4.6, custom CSS can be added using the plugins_css option in params.toml.

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:

• Create a new widget
• Create a new shortcode

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.

Date Format

Academic uses the following constants to format dates and times:

To modify the format, edit date_format and time_format in config/_default/params.toml using the above constants. For example, some common formats are: