Build your homepage with Wowchemy Page Builder

Building beautiful pages is easy with Wowchemy’s no-code block system.

No programming is required, just choose your blocks and arrange them how you like!

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

Blocks (aka widgets) empower you to fully customize your site. They display as sections on the homepage or on landing pages.

Multiple pre-designed blocks can be added, removed, and positioned as desired on your page. For example, you can use the Experience block in an “Experience” section and in an “Education” section on your homepage.

Looking to build and publish a block that doesn’t exist yet? Create a new block - or just paste your shiny new HTML layout into the Blank block together with your content.

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

How do I use blocks?

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 blocks

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

The following blocks support this option: 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


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

  columns: '1'  # 1 or 2 column layout
  view: compact  # Since v5.5+, write the view name, otherwise use the view ID 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

The Academicons icon pack, icon_pack: ai, includes the following academic icons:

  • cv, google-scholar, arxiv, orcid, researchgate, mendeley
  • See all icons

You can enable the academic icon pack extension in params.yaml:

    enable: true

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 - or just use your emoji keyboard directly

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


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:

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

Gradient background:

    # Choose colors such as from
    gradient_start: '#4bb4e3'
    gradient_end: '#2b94c3'
    # The gradient angle from 0-360 degrees
    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

Video background:

      # Name of video in `assets/media/`.
      path: background-video.mp4
      # Post-processing: flip the video horizontally?
      flip: false

You can also specify a background color (see Color Background) similar to the video for a better user experience whilst the video is loading.


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