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!
- ❤️ Become a backer on Patreon or GitHub and unlock these rewards and extra features
- ⭐️ Star Wowchemy on GitHub
- 👩💻 Contribute code, PR reviews, documentation, color themes, tutorials, etc.
Templates come with some popular Widgets preconfigured as homepage sections.
Delete the sections in
content/home/ that you don’t need (or set
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
contact-me.md, you can update the
/#contact link in
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: https://wowchemy.com/docs/page-builder/ 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 subtitle: # Section design design: # Use a 1-column layout columns: "1" # Use a dark navy background with light text. background: 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
my-section.md, 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
To remove a navigation link from the top of the page, remove the associated
main menu entry in
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.
Link to a section
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:
main: - name: Research url: /#research weight: 10
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
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
design: # 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 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
params.yamlto APA or MLA
- Showcase (5)
- 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
<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 ... design: 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.
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 = trueunder
Icon pack “emoji” gives you the ability to use emojis as icons
- See all icons
- Enter the emoji shortcode, such as
:, in Wowchemy’s
- 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
.svgextension) in the
- 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
text_color_light options and delete the rest (delete
gradient*). For colors, any HTML color name or Hex value is valid.
The following excerpts show the front matter structure for defining various backgrounds.
design: background: color: 'navy' # Text color (true=light, false=dark, or remove for the dynamic theme color). text_color_light: true
design: 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
design: 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).
design: spacing: # 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
advanced: css_style: '' css_class: ''