Layouts & Shortcodes

Page layouts and shortcodes for creating rich content

Page layouts

The theme includes several pre-built layouts for different content types.

Splash layout

Perfect for homepages. Includes hero section, page content, and recent blog posts.

---
title: "Homepage"
layout: "splash"
hero:
  title: "Welcome"
  subtitle: "Your tagline"
  excerpt: "Description"
  image:
    src: "images/hero.jpg"
    alt: "Hero image description"
---

Docs layout

Documentation pages with automatic sidebar navigation (like this page!).

---
title: "Documentation"
layout: "docs"
excerpt: "Page description"
---

The sidebar automatically generates from your page headings (h2, h3).

Blog layouts

Single Post (blog/single) - Individual blog post layout with clean typography

Blog Listing (blog/list) - Blog listing page with:

  • Featured section for most recent post
  • Category filtering
  • Responsive grid layout
  • Pagination

Single Item (gallery/single) - Individual gallery item with images

Gallery Grid (gallery/list) - Gallery grid with filtering capabilities

Creating content

Blog posts

Blog posts live in content/blog/. Each post requires front matter:

---
title: "My Blog Post"
date: 2025-12-28
draft: false
excerpt: "Short summary for listings"
image:
  src: "images/featured-image.jpg"
  alt: "Description for accessibility"
  credit: "Photo by Jane Doe on Unsplash"  # optional
category: "Tutorial"
show_author: false
tags:
  - hugo
  - web-development
---

Your post content in Markdown...

If you’ve enabled the gallery feature, create items in content/gallery/:

---
title: "Item Name"
groups: ["category1", "category2"]
hero:
  title: "Item Title"
  subtitle: "Description"
  image:
    src: "images/item-image.jpg"
    alt: "Image description"
---

Additional details about this item...

Use Hugo’s archetype to create new gallery items:

hugo new gallery/item-name/index.md

Shortcodes

Shortcodes let you add special content types in Markdown without writing HTML.

Figure

Add images with captions and automatic WebP support:

{{< figure 
  src="/images/photo.png" 
  alt="Description" 
  caption="Caption text with **Markdown** support"
>}}

The shortcode automatically looks for a WebP version (photo.webp) and uses it for modern browsers with PNG/JPG fallback.

Admonitions

Create callout boxes for important information:

{{< admonition type="info" title="Optional Title" >}}
Your message here with **Markdown** support.
{{< /admonition >}}

Available types: info, success, warning, danger, note

Example:

Pro Tip
Admonitions are great for highlighting important information in documentation!

Cards

Create card layouts:

{{< card title="Card Title" icon="fa-solid fa-star" >}}
Card content with **Markdown** support.
{{< /card >}}

Two-card row

Display two cards side-by-side:

{{< two-card-row >}}

{{< card title="First Card" >}}
Content for first card
{{< /card >}}

{{< card title="Second Card" >}}
Content for second card
{{< /card >}}

{{< /two-card-row >}}

Single card wide

Full-width card for emphasis:

{{< single-card-wide title="Wide Card" icon="fa-solid fa-gift" >}}
Content that spans the full width
{{< /single-card-wide >}}

Impact cards

Display front matter cards in an impact layout:

---
cards:
  - title: "Feature One"
    icon: "fa-solid fa-star"
    excerpt: "Description"
  - title: "Feature Two"
    icon: "fa-solid fa-bolt"
    excerpt: "Description"
---

{{< impact-cards >}}

Blog list

Display recent blog posts on any page:

{{< blog-list title="Recent Posts" limit=3 >}}

Section heading

Add styled section headings:

{{< section-heading
  title="Section Title"
  subtitle="Optional subtitle • With separators"
>}}

Metrics bar

Display key statistics:

{{< metrics-bar
  stat1="**100%** customizable"
  stat2="**15+** shortcodes"
  stat3="**3** layouts"
  stat4="**WCAG AA** accessible"
>}}

YouTube

Embed YouTube videos:

{{< youtube id="VIDEO_ID" >}}

The video ID is the string after v= in the YouTube URL.

Feature section

Display structured features from front matter:

---
feature_section:
  title: "What I've Built"
  subtitle: "Your subtitle"
  sections:
    - title: "Section Title"
      lead: "Optional lead paragraph"
      items:
        - bold: "Bold Text:"
          text: " Rest of the text"
        - text: "Plain text item"
        - text: "Linked Item"
          url: "https://example.com"
---

{{< feature-section >}}

Customization

Custom CSS

Add custom styles in assets/css/custom.scss (create if it doesn’t exist). The theme will automatically include it.

Custom JavaScript

Add custom scripts to static/js/ and reference them in your templates or content.

Override templates

To customize a template, copy it from themes/clean-hugo/layouts/ to your site’s layouts/ directory with the same path. Your version will override the theme’s version.

Example: To customize the footer, copy:

  • From: themes/clean-hugo/layouts/partials/footer.html
  • To: layouts/partials/footer.html

Next steps

Last modified: