Build your homepage with Wowchemy Page Builder

Building beautiful pages is easy with Wowchemy’s widget system. No programming is required!

Loading pre-made layouts is a great way to kickstart your new homepage. Templates come with some popular Widgets preconfigured for this purpose.

Widgets empower you to fully customize your site. They display as sections on the homepage or on landing pages.

Multiple widget instances can be added, removed, and positioned as desired on your page. For example, you can use the Experience widget in an “Experience” section and in an “Education” section on your homepage.

Table of Contents

Wowchemy comes with the following widgets built-in.

Looking to build and publish a Wowchemy widget that doesn’t exist yet? Create a new widget.

  • Blank - add any elements such as an image gallery
  • Hero - encourage visitors to perform an action (CTA)
  • About Me - introduce yourself
  • Skills / Features - showcase skills or key features of a product
  • Experience / Education - list your professional experience on a timeline
  • Accomplishments - showcase your (online learning) certificates and other achievements
  • Content Feed - display recent blog posts, events, and publications
  • Featured Content - display featured (sticky) blog posts, events, and publications
  • Contact - display your contact details, including an optional contact form and map
  • Portfolio - showcase your work or product features in a filterable portfolio
  • Tag cloud - enable visitors to discover popular topics
  • Team Members - introduce your team members
  • Slider (carousel) - promote a lot of content in a small space

We’re full steam ahead on improving Wowchemy, and we need your help!

Using Widgets

Templates come with some popular Widgets preconfigured as homepage sections.

Delete the sections in content/home/ that you don’t need (or set active to false in their front matter) and personalize the front matter options of the sections that you wish to keep by opening them in a text editor (such as by clicking the pencil icon in your GitHub project).

The sections (widget instances) in your home/ folder can be renamed to anything you like (but use hyphens instead of spaces). Just remember to update your main menu in config/_default/menus.yaml if you have a link to the widget instance. For example, if you rename to, you can update the /#contact link in menus.yaml to /#contact-me.

Create a section

To add a section to the homepage, create a new Markdown file in your content/home/ folder, for example

Explore this page to find the widget you wish to use in your section. Then copy and paste the widget’s front matter options into your new Markdown file.

Remember to place your front matter options between a pair of triple dashes --- to represent YAML, for example:

# An instance of the Blank widget.
# Documentation:
widget: blank

# This file represents a page section.
headless: true

# Order that this section appears on the page.
weight: 1

# Section title
title: Hello

# Section subtitle

# Section design
  # Use a 1-column layout
  columns: "1"
  # Use a dark navy background with light text.
    color: 'navy'
    text_color_light: true

Add any content to the body of the section here.

You can also add any common widget options documented on this page, such as title, to the front matter.

You can link a homepage section from the site menu by editing config/_default/menus.yaml and adding the filename of your section. For example, if your section is named, reference it as "/#my-section" in the menu URL.

You can create as many instances of widgets as you wish, with each appearing in its own section.

Remove a section

If you do not require a particular widget, you can simply delete any associated files from the content/home/ folder.

To remove a navigation link from the top of the page, remove the associated main menu entry in config/_default/menus.yaml.

Position sections

The order that the homepage widgets are displayed in is defined by the weight parameter in each of the files in the content/home/ directory. The widgets are displayed in ascending order of their weight, so you can simply edit the weight parameters as desired.

You may wish to add a navigation link to the top of the page that points to a section. This can be achieved by adding something similar to the following lines to your config/_default/menus.yaml, where the URL will consist of the first title word in lowercase:

  - name: Research
    url: /#research
    weight: 10

Personalizing Widgets

The parameters for each section consist of general options in addition to widget-specific options. When you open a section installed in the content/home/ folder in a text editor, the available options will be displayed in the front matter.

We recommend using YAML formatted front matter (between a pair of ---). If your front matter is written in TOML syntax (between a pair of +++), you’ll need to convert it before using the YAML formatted snippets on this page.

Generally, if you write any text in the file body after a widget’s front matter, your text will appear at the top of the widget. This can be useful for introducing the widget content.

A title and subtitle can be set for most widgets using the title and subtitle options respectively.


The number of columns in a section can be configured for most widgets. Valid options are:

  • '1': a single full-width column with the section content appearing directly underneath the section title (if set)
  • '2': two columns in the classic Wowchemy layout with the the section title appearing on the left and the section content appearing on the right

Supported widgets (as of v5.0.0.beta1): pages, featured, experience, accomplishments, contact, blank, tag_cloud, portfolio

For example:

  # Choose how many columns the section has. Valid values: '1' or '2'.
  columns: '1'


Several widgets have a view option to let you choose how content is displayed.

The _showcase_ view
The showcase view

The following content previews are available:

  • List (1)
  • Compact (2)
  • Card (3)
  • Citation (4)
    • For classic APA or MLA styled publication lists
    • Optionally, edit the value of citation_style in params.yaml to APA or MLA
  • Showcase (5)
  • Masonry
    • Intended for use with the Portfolio widget to provide a Pinterest-style layout
  • Or, create your own view in layouts/partials/views/community/<name>.html (creating the folders) and reference it as view: community/<name> where <name> is a unique name for your view (with no spaces in the name)
    • take a look at the code for the built-in views for inspiration
    • consider sharing your new view with the Community on Discord, or publishing it as a Hugo Module
    • supports Wowchemy versions from 2021-12-18 (v5.5 dev) onwards


# In your content/home/<widget>.md ...

  columns: '1'  # 1 or 2 column layout
  # view: compact  # For new versions since v5.5+, write the view name
  view: 2  # For older versions prior to v5.5, use the numeric IDs above
  flip_alt_rows: true # Flip alternate rows when in Showcase view?

What text is shown in the preview?

The built-in listings get the summary text for each listing from the page’s summary or abstract field. If you don’t provide that field, then Hugo will automatically generate a summary. You can also use Hugo’s <!–more–> summary divider in the body of your content, where you want to split the article.


Wowchemy enables you to use a wide range of icons from Font Awesome and Academicons.

Icon pack “fab” includes the following brand icons:

  • twitter, weixin, weibo, linkedin, github, facebook, pinterest, twitch, youtube, instagram, soundcloud
  • See all icons

Icon packs “fas” and “far” include the following general icons:

  • fax, envelope (for email), comments (for discussion forum)
  • See all icons

Icon pack “ai” includes the following academic icons:

  • cv, google-scholar, arxiv, orcid, researchgate, mendeley
  • See all icons
  • To enable the academic icon pack in v5+, set ai = true under [icon.pack] in params.yaml

Icon pack “emoji” gives you the ability to use emojis as icons

  • See all icons
  • Enter the emoji shortcode, such as :heart:, in Wowchemy’s icon field
  • Wowchemy v4.9+ is required to utilise the emoji icon pack and can currently only be used in the Featurette (skills) widget.

Icon pack “custom” gives you the ability to use custom SVG icons

  • Create an SVG icon in your favorite image editor or download one from a site such as Flat Icon
  • Place the custom SVG icon in assets/media/icons/, creating the folders if necessary
  • Reference the SVG icon name (without .svg extension) in the icon field
  • Wowchemy v4.9+ is required to utilise the custom icon pack and can currently only be used in the Featurette (skills) widget.


A background can easily be applied to any homepage section. Choose from a range of background options including color, gradient, and image. Then choose either a dark or light text color by setting text_color_light, or remove text_color_light for dynamic text color associated with the current light/dark theme.

Once you have chosen the type of background, delete or comment out (by prefixing #) any unused options. For example, if you choose an image background, set the image* and text_color_light options and delete the rest (delete color and gradient*). For colors, any HTML color name or Hex value is valid.

The following excerpts show the front matter structure for defining various backgrounds.

Color background:

    color: 'navy'
    # Text color (true=light, false=dark, or remove for the dynamic theme color). 
    text_color_light: true

Gradient background:

    gradient_start: '#4bb4e3'
    gradient_end: '#2b94c3'
    gradient_angle: 180
    # Text color (true=light, false=dark, or remove for the dynamic theme color).
    text_color_light: true

Image background:

    # Name of image in `assets/media/`.
    image: background.jpg
    # Darken the image? Range 0-1 where 0 is transparent and 1 is opaque.
    image_darken: 0.6
    #  Options are `cover` (default), `contain`, or `actual` size.
    image_size: cover
    # Options include `left`, `center` (default), or `right`.
    image_position: center
    # Use a fun parallax-like fixed background effect on desktop? true/false
    image_parallax: true
    # Text color (true=light, false=dark, or remove for the dynamic theme color).
    text_color_light: true


The spacing of sections can be controlled by specifying padding for the top, right, bottom, and left sides of sections.

For example, to make a section more compact, the following parameters can be added to the front matter of a section. This example will reduce the top and bottom spacing of the section to just 20 pixels (px).

    # Customize the section spacing. Order is top, right, bottom, left.
    padding: ["20px", "0", "20px", "0"]


It’s possible to customize the style of a specific instance of a widget with CSS. For example, the font size of a section can be changed.

First, define your custom style in CSS using the CSS Plugin feature.

To apply your new style to a widget, set css_class in a widget’s front matter. For example css_class = "MY_CSS_CLASS", where MY_CSS_CLASS is the name of the CSS class which you defined in the previous step.

Custom CSS code can also be directly applied to a section using the css_style option.

  css_style: ''
  css_class: ''