clean-hugo theme: blog formatting and shortcode reference

This post is a living reference for the clean-hugo theme. Every shortcode and content-formatting option available in the theme is demonstrated here with a working example and the code that produces it. Use this post to test that a theme change has not broken existing content, and as a copy-paste resource when writing new blog posts.

Figures

The figure shortcode renders images with optional captions and automatic WebP support. It generates a <picture> element with a WebP <source> and a fallback <img>. If a .webp file exists alongside the source image, modern browsers use it automatically.

Usage:

{{< figure
  src="images/pyopensci-general/pyopensci-timeline2019-2024.png"
  alt="Descriptive alt text."
  caption="Optional caption with **Markdown** support."
  link="images/pyopensci-general/pyopensci-timeline2019-2024.png"
>}}

Rendered:

Parameters:

Admonitions

The admonition shortcode creates highlighted callout boxes. Five types are available. An optional title param adds a heading inside the box.

Usage:

{{< admonition type="info" title="Optional title" >}}
Content with **Markdown** support.
{{< /admonition >}}

All five types rendered:

Rendered:

Without a title:

Admonition quotes

The admonition-quote shortcode renders a quotation inside an admonition-style callout box. It uses the same type variants as admonition, with a single opening quote mark at the top (no closing quote). Optional title, author, and event params are supported.

Same quote text in each example so you can compare styles.

Note:

{{< admonition-quote type="note" title="Note quote" author="Anonymous" event="AGU 2019 Townhall" >}}
Good research software is built for the people who use it.
{{< /admonition-quote >}}

Rendered:

Info:

{{< admonition-quote type="info" >}}
Good research software is built for the people who use it.
{{< /admonition-quote >}}

Rendered:

Warning:

{{< admonition-quote type="warning" title="A community reminder" >}}
Good research software is built for the people who use it.
{{< /admonition-quote >}}

Rendered:

Success:

{{< admonition-quote type="success" author="pyOpenSci community member" >}}
Good research software is built for the people who use it.
{{< /admonition-quote >}}

Rendered:

Danger:

{{< admonition-quote type="danger" >}}
Good research software is built for the people who use it.
{{< /admonition-quote >}}

Rendered:

Parameters:

Blockquotes

Plain Markdown blockquotes are for inline citations in the flow of a post — a left border, light background, and Lora italic body text. No shortcode is required.

Use a pull quote when you want the same quote typography with a decorative opening mark and no sidebar box. Use a feature quote for compact sidebar-style quotes (home page project block, two-column layouts). Use an admonition quote when the quote should sit inside a colored callout box.

Single paragraph:

> Good research software is built for the people who use it.

Good research software is built for the people who use it.

With attribution (written in Markdown):

> Good research software is built for the people who use it.
>
> — **pyOpenSci community member**, *Peer review guide*

Good research software is built for the people who use it.

— pyOpenSci community member, Peer review guide

Multi-line quote:

> Good research software is built for the people who use it.
>
> Quotes can span multiple paragraphs when you need more room.

Good research software is built for the people who use it.

Quotes can span multiple paragraphs when you need more room.

Nested in a list (blockquote inside list item):

* Before you submit, read the packaging guide.
* Remember the goal of review:

  > Good research software is built for the people who use it.

* Then open your submission issue on GitHub.

• Before you submit, read the packaging guide.

• Remember the goal of review:

  Good research software is built for the people who use it.

• Then open your submission issue on GitHub.

Pull quotes

The pullquote shortcode uses the same Lora quote text as blockquotes, with a decorative opening mark above and no left border or background. Three accent colors are available for the mark. Optional author and event params add attribution.

Same quote text in each example so you can compare colors.

Teal (default):

{{< pullquote color="teal" author="Anonymous" event="AGU 2019 Townhall" >}}
Good research software is built for the people who use it.
{{< /pullquote >}}

Rendered:

Magenta:

{{< pullquote color="magenta" >}}
Good research software is built for the people who use it.
{{< /pullquote >}}

Rendered:

Purple:

{{< pullquote color="purple" author="pyOpenSci community member" >}}
Good research software is built for the people who use it.
{{< /pullquote >}}

Rendered:

Parameters:

Feature quotes

The feature-quote shortcode renders a compact quote with a Font Awesome opening mark and Nunito Sans italic text at 1.3rem — no left border or gray background. This is the same style used in the home page Current project block. Three accent colors match the pull quote palette.

Purple (default):

{{< feature-quote cite="Eliot Robson" >}}
Gen AI solutions remind us that the centerpiece of open-source software is
building a community around solving a specific problem.
{{< /feature-quote >}}

Rendered:

Teal:

{{< feature-quote color="teal" cite="Anonymous" >}}
Good research software is built for the people who use it.
{{< /feature-quote >}}

Rendered:

Magenta:

{{< feature-quote color="magenta" >}}
Good research software is built for the people who use it.
{{< /feature-quote >}}

Rendered:

Parameters:

Buttons

The button shortcode renders a styled CTA link. Variants use pyOpenSci brand colors. Default and large (size="lg") sizes are supported.

Dark purple:

{{< button href="/blog/" variant="dark-purple" >}}
Dark purple
{{< /button >}}

Rendered:

White:

{{< button href="/blog/" variant="white" >}}
White
{{< /button >}}

Rendered:

Green:

{{< button href="/blog/" variant="green" >}}
Green
{{< /button >}}

Rendered:

Light purple:

{{< button href="/blog/" variant="light-purple" >}}
Light purple
{{< /button >}}

Rendered:

Outline:

{{< button href="/blog/" variant="outline" >}}
Outline
{{< /button >}}

Rendered:

Large:

{{< button href="/blog/" variant="dark-purple" size="lg" >}}
Large button
{{< /button >}}

Rendered:

With icon (right):

{{< button href="/blog/" variant="dark-purple" icon="arrow-right" iconPosition="right" >}}
Continue reading
{{< /button >}}

Rendered:

With icon (left):

{{< button href="https://github.com/pyOpenSci" variant="outline" icon="github" target="_blank" >}}
View on GitHub
{{< /button >}}

Rendered:

Parameters:

YouTube

The youtube shortcode embeds a YouTube video in a responsive 16:9 container. Pass the video ID from the URL (the part after v=).

Usage:

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

Rendered:

Blog list

The blog-list shortcode pulls the most recent blog posts and renders them as listing cards. Use it on any page to surface recent content.

Usage:

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

Rendered:

Parameters:

Impact card grid

The impact-cards shortcode renders a responsive card grid from the page cards: front matter. Card types include image highlights, white icon cards, and large text_only headline cards. Set cards_layout: wide in front matter for a three-column desktop grid.

Usage (front matter + shortcode):

cards:
  - text_only: true
    title: "Large text card"
  - modifier: "card--white"
    icon: "fa-solid fa-mobile-screen"
    title: "White card with icon"
    excerpt: "Icon, title, and body text."
  - title: "Teal highlight card"
    icon: "fa-solid fa-code"
    excerpt: "Default modifier uses primary-light background."

{{< impact-cards >}}

Rendered (uses the demo cards: on this page):

Feature row

Side-by-side image and text with an optional button. Use on landing pages inside swoosh sections.

Usage:

{{< feature-row layout="left"
    title="Feature row title"
    image="/images/landing-pages/scipy-sprint-working.png"
    alt="Descriptive alt text."
    buttonUrl="/about-peer-review/"
    buttonLabel="Learn more" >}}
Markdown body copy with **formatting** support.
{{< /feature-row >}}

Rendered:

Feature row example

Markdown body copy with formatting support. Layout can be left, right, or center.

About peer review

Swoosh section

Full-width band with optional curved dividers. When nesting other shortcodes inside, use Hugo’s HTML shortcode form (angle brackets), not the markdown shortcode form (percent signs).

Usage:

{{< swoosh_section background="purple" swoosh="bottom" >}}
{{< section-heading title="Inside a swoosh" >}}
{{< /swoosh_section >}}

Rendered:

Intro section

Renders intro_section.text from page front matter — typically placed below a hero on splash pages.

Usage:

intro_section:
  text: "Lead paragraph shown in the intro band."

{{< intro-section >}}

Rendered:

Connect with pyOpenSci

Admonition-style callout with community links and social follow list.

Usage:

{{< connect-with-pyos >}}

Rendered:

Recent contributors

Grid of the most recently added people from data/contributors.yml.

Usage:

{{< recent-contributors limit="2" >}}

Rendered:

pyOpenSci has a diverse and vibrant community of pythonistas! To date, 392 wonderful people have contributed to pyOpenSci.

Britney Whittington

STScI

Abby Mitchell

@facebook

Recent packages

Grid of recently accepted packages from data/packages.yml.

Usage:

{{< recent-packages limit="2" >}}

Rendered:

Upcoming events

Event cards from content/events/ (upcoming dates only).

Usage:

{{< upcoming-events limit="2" >}}

Rendered:

Where you can find us

22–26 JUN

Community event

UN Open Source Week 2026

UN Open Source Week 2026 • New York City

Learn more →

13–19 JUL

Talk

EuroPython 2026 (placeholder)

EuroPython 2026 • Kraków, Poland

Learn more →

View all events

Training feature

Home-page training strip — reads training_feature from page front matter.

Usage:

training_feature:
  eyebrow: "Training"
  badge: "New cohort"
  title: "Course title"
  excerpt: "Short description."
  button_label: "Learn more"
  button_url: "/events/"
  image:
    src: "images/landing-pages/scipy-sprint-2026.png"
    alt: "Alt text."

{{< training-feature >}}

Rendered:

Demo

Reference

Training feature strip

Side-by-side image and CTA — used on the home page.

Browse events

Current project

Full-width quote band used on the home page — reads current_project from front matter.

Usage:

current_project:
  eyebrow: "Current project"
  title: "Headline"
  excerpt: "Supporting text."
  quote: "Quote text."
  cite: "Attribution"
  button_label: "Get involved"
  button_url: "/events/"

{{< current-project >}}

Rendered:

Editorial board

People grids for editorial board and emeritus editors from data/contributors.yml. Used on program landing pages.

Usage:

{{< editorial-board >}}

Rendered:

Meet our editorial board

The pyOpenSci software peer review process is led by a volunteer team of editors from the scientific Python community. Editors do the following things:

• They find reviewers from diverse backgrounds who have a mixture of scientific domain and Python experience.
• They oversee the entire review process for a package ensuring it runs in a timely and efficient manner.
• They support the submitting authors and reviewers in answering questions related to the review.
• They determine whether that package should be accepted into the pyOpenSci ecosystem once the review has wrapped up.

Learn more about the editor role at pyOpenSci in our peer review guide.

Filipe

Advisory Council, Editor

Eliot Robson

Peer Review Lead, Editor, Emeritus Editor in Chief

UIUC

Alexander Hasson

Editor

Romain Caneill

Editor

Institut des Géosciences de l'Environnement

Lauren Yee

Editor, Editor in Chief

David Nicholson

Emeritus Editor in Chief, Editor

Szymon Moliński

Editor

Sare

Tom Russell

Editor

University of Oxford

C. Titus Brown

Editor

University of California, Davis

Hans Moritz Günther

Editor

MIT

Sebastian Lobentanzer

Bane Sullivan

Editor

Derek Homeier

Editor

Tetsuo Koyama

@ark-info-sys

Kelly L. Rowland

Silvana Ovaitt

Avik Basu

Editor

Intuit

Julieta Millan

Editor

Carter Lee Rhea

Editor

Jonas Eschle

Editor

CERN

Emeritus & guest editors

We are deeply grateful for those served on our editorial board previously!

Ivan Ogasawara

Advisory Council, Emeritus editor

xmnlab

Chiara Marmo

Emeritus Editor in Chief, Emeritus Editor, Peer review triage

Luiz Irber

Emeritus editor

Ben Cook

Guest editor

Russ Biggs

Leah Wasser

Executive Director & Founder, Emeritus editor

pyOpenSci

Alex Batisse

Emeritus Editor in Chief, EmeritusEditor

Jonny Saunders

Emeritus Editor

Meenal Jhajharia

Emeritus Editor

\varnothing

Isabel Zimmerman

Emeritus Editor in Chief, Emeritus Editor

@rstudio

Nima Sarajpoor

Emeritus Editor

Ariane Sasso

Emeritus Editor

@hpi-dhc

Jenny Palomino

Emeritus Editor

Google

Anita Graser

Emeritus Editor

Landing-page shortcodes (reference only)

These shortcodes are used on specific splash pages and require matching front matter or site data. They are listed here for completeness; see CONTRIBUTING.md for layout details.

Section heading

The section-heading shortcode renders a large centred heading with an optional subtitle. Useful at the top of long posts to establish visual hierarchy.

Usage:

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

Rendered:

Metrics bar

The metrics-bar shortcode renders a row of key statistics with large numbers. Use it to highlight impact data.

Usage:

{{< metrics-bar
  stat1="**128** blog posts"
  stat2="**500+** community members"
  stat3="**100+** reviewed packages"
  stat4="**WCAG AA** accessible"
>}}

Rendered:

Cards

Three card shortcodes are available for structured content blocks.

Two-card row

Usage:

{{< two-card-row >}}
{{< card title="Card one" icon="fa-solid fa-star" >}}
Content for the first card with **Markdown** support.
{{< /card >}}
{{< card title="Card two" icon="fa-solid fa-bolt" >}}
Content for the second card.
{{< /card >}}
{{< /two-card-row >}}

Rendered:

Single card wide

Usage:

{{< single-card-wide title="Wide card" icon="fa-solid fa-users" >}}
Full-width card content here.
{{< /single-card-wide >}}

Rendered:

Standard Markdown elements

These are not shortcodes — they are standard Markdown rendered by Hugo. Include them here so a full blog post render covers all common content types.

Code blocks

Inline: python3 -m pip install pyopensci

Fenced block with syntax highlighting:

import pyopensci

# Submit a package for review
package = pyopensci.Package(
    name="mypackage",
    version="1.0.0",
    github_url="https://github.com/example/mypackage",
)
package.submit()

hugo serve --buildDrafts --disableFastRender

Blockquotes

See Blockquotes above for full examples. Quick render check:

> Good research software is built for the people who use it.

Good research software is built for the people who use it.

Tables

Default Markdown tables render with basic styling. For sponsorship tier tables (and similar comparison layouts), use the partnership_table shortcode so the table matches the live site: light purple header row, horizontal row dividers, and bold purple tier names in the first column.

{{< partnership_table >}}
| Tier | Example focus | Example visibility & benefits |
| --- | --- | --- |
| **Ecosystem catalyst** | Companies ready to lead in supporting open source research software | Premier placement across channels; tailored activations such as mentored sprints and dedicated office hours |
| **Momentum driver** | Teams growing their scientific Python footprint | Sustained visibility on the website and in mailings; alignment with webinars and community programs |
| **Foundation builder** | Organizations beginning to invest in open science education | Recognition alongside training materials; support for scholarships and learner access |
{{< /partnership_table >}}

Rendered:

Plain table (no wrapper):

Lists

Unordered:

• First item
• Second item
  • Nested item
  • Another nested item
• Third item

Ordered:

1. Step one
2. Step two
3. Step three