Blocks and shortcodes

This port covers the Academic CV block set, the common **marketing /
landing blocks**, and the shortcodes most used in content. Unknown block
ids fall through to a markdown block so a typo doesn't blank the page.

Each block below shows a live preview and the YAML that produced it. A full
composed landing also lives on the Block showcase.

Landing blocks

Declare blocks in a page's sections: list (template: landing). Author profiles live inline under content.author (same shape as upstream data/authors/me.yaml).

`resume-biography-3` (alias: `biography`)

Hero profile — name/pronouns/role, affiliations, social icons, bio, CTA, education cards, interest pills.

Example

- block: resume-biography-3
  content:
    author:
      name:
        display: Ada Lovelace
        pronouns: she/her
      role: Research scientist
      bio: Short bio with **markdown**.
      links:
        - icon: brands/github
          url: 'https://github.com/HugoBlox/hugo-blox-builder'
          label: GitHub
      interests:
        - Machine learning
        - Docs
      education:
        - area: Mathematics
          institution: University of London
          date_start: '1830-01-01'
    button:
      text: Browse publications
      url: /publications/
  design:
    background:
      gradient_mesh:
        enable: true

Preview

Ada Lovelace

(she/her)

Research scientist

Professional Summary

Short bio with markdown.

Browse publications

Education

Mathematics

University of London

Interests

Machine learningDocs

`markdown`

Titled prose section. Inline markdown in `title` / `text`.

Example

- block: markdown
  content:
    title: Research
    text: 'Speak to your mission here. **Bold** and [links](/) work.'

Preview

Research

Speak to your mission here. Bold and links work.

`collection` (alias: `content-collection`)

Renders a named entry from the page's `collections:` map. Views: `card`, `article-grid`, `citation`, `date-title-summary`. This page declares `pubs` → `/publications`.

Example

- block: collection
  content:
    title: Publications
    collection: pubs
    count: 3
    archive:
      enable: true
      link: /publications/
      text: See all
  design:
    view: citation

Preview

Publications

Ada Lovelace (2024). An example preprint. arXiv.

Ada Lovelace, Robert Ford (2015). An example journal article. Journal of Source Themes, 1(1).

Ada Lovelace, Robert Ford (2013). An example conference paper. ICW.

See all

`resume-experience` (alias: `experience`)

Work + education timelines. Work items use `role` / `org` (or `position` / `company_name`).

Example

- block: resume-experience
  content:
    author:
      experience:
        - role: Research Scientist
          org: Analytical Engines Lab
          date_start: '2020-01-01'
          summary: Leading documentation tooling.
      education:
        - area: Computer Science
          institution: University of London
          date_start: '2012-01-01'
          date_end: '2016-01-01'

Preview

Experience

Research Scientist

Analytical Engines Lab

Jan 2020 – Present

Leading documentation tooling.

Education

Computer Science

University of London

Jan 2012 – Jan 2016

`resume-skills` (alias: `skills`)

Grouped skill bars. Items use `level` 0–5. Optional `design.columns`.

Example

- block: resume-skills
  content:
    title: Skills
    author:
      skills:
        - name: Technical
          items:
            - name: TypeScript
              level: 5
            - name: Deno
              level: 4
        - name: Writing
          items:
            - name: Technical writing
              level: 4

Preview

Skills

Technical

TypeScript

Deno

Writing

Technical writing

`resume-awards` (alias: `awards`)

Award cards from `author.awards` — optional `url` and `certificate_url`.

Example

- block: resume-awards
  content:
    title: Awards
    author:
      awards:
        - title: Best Paper
          awarder: Hugo Blox Conference
          date: '2024-01-01'
          summary: Top 5 of 8000 submissions.
          url: 'https://example.com/award'

Preview

Awards

Best Paper

Hugo Blox Conference ∙ January 2024

Top 5 of 8000 submissions.

`resume-languages` (alias: `languages`)

Progress rings. Use `percent` (0–100) or numeric `level` (0–5 → ×20).

Example

- block: resume-languages
  content:
    title: Languages
    author:
      languages:
        - name: English
          percent: 100
        - name: French
          level: '3.5'
          label: Conversational

Preview

Languages

100%

English

70%

FrenchConversational

`cta-card`

Full-width call-to-action with title, text, and button.

Example

- block: cta-card
  content:
    title: Build your own academic site
    text: Install from JSR and compose landing pages from blocks.
    button:
      text: Using Blox
      url: /theme-docs/

Preview

Build your own academic site

Install from JSR and compose landing pages from blocks.

Using Blox

Marketing & content blocks

Same sections: authoring as above. A composed landing lives on the Block showcase.

`hero`

Headline + dual CTAs. Layouts: `stacked`, `split-left`, `split-right`.

Example

- block: hero
  content:
    eyebrow: Hugo Blox for Dune
    title: 'Landing blocks, ported'
    text: Faithful Academic CV and marketing sections.
    primary_action:
      text: Using Blox
      url: /theme-docs/
    secondary_action:
      text: Homepage
      url: /
      style: outline
  design:
    layout: stacked

Preview

Hugo Blox for Dune

Landing blocks, ported

Faithful Academic CV and marketing sections.

Using Blox Homepage

`dev-hero`

Developer greeting with optional typewriter strings (`blox.js`).

Example

- block: dev-hero
  content:
    greeting: 'Hi, I''m'
    name: Ada Lovelace
    role: Research scientist
    bio: I build documentation systems.
    links:
      - icon: brands/github
        url: 'https://github.com/HugoBlox/hugo-blox-builder'
        label: GitHub
    typewriter:
      enable: true
      prefix: 'I work on '
      strings:
        - docs
        - DX
        - open science
    cta_buttons:
      - text: Publications
        url: /publications/

Preview

Hi, I'm

Ada Lovelace

I work on

I build documentation systems.

Publications

`features`

Icon grid. `design.layout`: `grid` (default) or `bento`.

Example

- block: features
  content:
    title: Why blocks
    subtitle: Compose pages
    items:
      - name: Academic CV
        description: 'Biography, experience, skills.'
        icon: academic-cap
      - name: Marketing
        description: 'Hero, pricing, FAQ, logos.'
        icon: sparkles
      - name: Collections
        description: Wire pubs and posts by name.
        icon: document-duplicate
  design:
    layout: grid

Preview

Compose pages

Why blocks

Academic CV

Biography, experience, skills.

Marketing

Hero, pricing, FAQ, logos.

Collections

Wire pubs and posts by name.

`stats`

Animated counters (`blox.js`). Layouts: `cards`, `compact`, `minimal`.

Example

- block: stats
  content:
    title: Impact at a glance
    items:
      - statistic: 120+
        description: Publications
        icon: book-open
      - statistic: '45'
        description: Collaborators
      - statistic: '12'
        description: Open-source projects
  design:
    layout: cards
    numbers_gradient: true

Preview

Impact at a glance

120+

Publications

45

Collaborators

12

Open-source projects

`faq`

Single-open accordion. Items accept `question`/`answer` or `title`/`text`.

Example

- block: faq
  content:
    title: FAQ
    items:
      - question: Are Academic CV blocks included?
        answer: 'Yes — biography, experience, skills, awards, languages, collections.'
      - question: What is still deferred?
        answer: Pagefind search-hero and help-center taxonomies.
    button:
      text: Adapting to Dune
      url: /theme-docs/adapting-to-dune/

Preview

FAQ

Yes — biography, experience, skills, awards, languages, collections.

Pagefind search-hero and help-center taxonomies.

Adapting to Dune

`logos`

Partners / sponsors. Layouts: `row`, `grid`, `marquee`. Style: `grayscale`, `color`, `white`.

Example

- block: logos
  content:
    title: Built with
    items:
      - name: Deno
        icon: brands/github
      - name: Hugo Blox
        icon: brands/github
        url: 'https://hugoblox.com'
      - name: Dune
        icon: brands/github
  design:
    layout: row
    logo_style: grayscale
    logo_size: md

Preview

Built with

`steps`

Process / how-it-works. Layouts: `vertical`, `horizontal`, `timeline`.

Example

- block: steps
  content:
    title: How it works
    items:
      - title: Install
        text: Add the theme from JSR.
        icon: arrow-down-tray
      - title: Configure
        text: 'Set menu, theme mode, and CTA.'
      - title: Compose
        text: Stack blocks on a landing page.
        cta:
          text: Docs
          url: /theme-docs/
  design:
    layout: horizontal

Preview

How it works

1
Install
Add the theme from JSR.
2
Configure
Set menu, theme mode, and CTA.
3
Compose
Stack blocks on a landing page.
Docs

Install

Add the theme from JSR.

Configure

Set menu, theme mode, and CTA.

Compose

Stack blocks on a landing page.

Docs →

`testimonials`

Quote cards. One item → featured; several → grid. `image` is an avatar URL.

Example

- block: testimonials
  content:
    title: What people say
    items:
      - name: Ada
        role: Research scientist
        text: The block vocabulary matches upstream Hugo Blox.
      - name: Charles
        role: Lab manager
        text: 'Stats, FAQ, and contact cover our homepage.'

Preview

What people say

“The block vocabulary matches upstream Hugo Blox.”

Ada

Research scientist

“Stats, FAQ, and contact cover our homepage.”

Charles

Lab manager

`pricing`

Tiers with optional monthly/yearly toggle (`blox.js`).

Example

- block: pricing
  content:
    title: Plans
    billing_toggle:
      enabled: true
      monthly_label: Monthly
      yearly_label: Yearly
      yearly_discount: Save 20%
    tiers:
      - name: Starter
        description: Personal academic site
        price:
          monthly: '0'
          yearly: '0'
          currency: $
        price_suffix: /mo
        cta:
          text: Get started
          url: /theme-docs/installing/
        features:
          - Academic CV blocks
          - Search modal
          - Dark mode
      - name: Lab
        highlight: true
        badge: Popular
        price:
          monthly: '29'
          yearly: '23'
          currency: $
        price_suffix: /mo
        cta:
          text: Contact
          url: /theme-docs/
          style: primary
        features:
          - text: Everything in Starter
            included: true
          - text: Team showcase
            included: true
          - text: Priority support
            included: false

Preview

Plans

MonthlyYearlySave 20%

Starter

Personal academic site

Free

Get started

Academic CV blocks
Search modal
Dark mode

Popular

Lab

$29/mo

Contact

Everything in Starter
Team showcase
Priority support

`comparison-table`

Feature matrix across competitors (desktop table / mobile cards).

Example

- block: comparison-table
  content:
    title: Compared
    competitors:
      - name: This port
        highlight: true
        badge: You are here
      - name: Upstream Hugo
    rows:
      - feature: Academic CV blocks
        values:
          - true
          - true
      - feature: Dune collections
        values:
          - true
          - false
      - feature: Pagefind search-hero
        values:
          - false
          - true

Preview

Compared

You are here

	This port	Upstream Hugo
Academic CV blocks
Dune collections
Pagefind search-hero

This port

You are here

Academic CV blocks
Dune collections
Pagefind search-hero

Upstream Hugo

Academic CV blocks
Dune collections
Pagefind search-hero

`focus-areas` (alias: `research-areas`)

Research theme cards. Layouts: `cards`, `hexagon`, `timeline`.

Example

- block: focus-areas
  content:
    title: Research themes
    items:
      - name: Documentation systems
        description: Tooling for researchers who write.
        status: active
        topics:
          - docs
          - DX
        gradient: from-primary-400 to-secondary-400
      - name: Open science
        description: Reproducible publishing pipelines.
        status: emerging
        topics:
          - open-source
        gradient: from-secondary-400 to-primary-400
  design:
    layout: cards

Preview

Research themes

Active

Documentation systems

Tooling for researchers who write.

docsDX

Emerging

Open science

Reproducible publishing pipelines.

open-source

`tech-stack`

Categorised tools. `design.style`: `grid` | `list`. Optional level bars.

Example

- block: tech-stack
  content:
    title: Tech stack
    categories:
      - name: Runtime
        items:
          - name: Deno
            icon: code-bracket
            level: expert
          - name: TypeScript
            icon: code-bracket
            level: expert
      - name: Content
        items:
          - name: Markdown
            icon: book-open
            level: advanced
  design:
    style: grid
    show_levels: true

Preview

Tech stack

Runtime

Deno

expert

TypeScript

expert

Content

Markdown

advanced

`contact-info`

Address, hours, email/phone, social, optional map link. Form only when `form_action` is set.

Example

- block: contact-info
  content:
    title: Contact
    visit_title: Visit
    connect_title: Connect
    text: Open to collaborations.
    address:
      lines:
        - Analytical Engines Lab
        - London
    office_hours:
      - 'Mon–Fri 10:00–16:00'
    email: ada@example.com
    social:
      - icon: brands/github
        url: 'https://github.com/HugoBlox/hugo-blox-builder'
        label: GitHub

Preview

Contact

Visit

Analytical Engines Lab

London

Office Hours

Mon–Fri 10:00–16:00

Connect

ada@example.com

Find me on

`cta-button-list`

Link-in-bio style button stack.

Example

- block: cta-button-list
  content:
    buttons:
      - text: Publications
        url: /publications/
        icon: book-open
      - text: Blog
        url: /blog/
        icon: document-duplicate
      - text: Using Blox
        url: /theme-docs/
        icon: sparkles

Preview

Publications

Blog

Using Blox

`cta-image-paragraph`

Alternating image + text rows (odd rows reverse).

Example

- block: cta-image-paragraph
  content:
    items:
      - title: Compose freely
        text: Stack marketing and CV blocks on any landing page.
        features:
          - YAML sections
          - Shared author maps
          - safeHref links
        button:
          text: Block showcase
          url: /theme-docs/block-showcase/

Preview

Compose freely

Stack marketing and CV blocks on any landing page.

YAML sections
Shared author maps
safeHref links

Block showcase

`team-showcase`

Inline people (not `content/authors/` pages). Use flat `people` or `groups`.

Example

- block: team-showcase
  content:
    title: Team
    people:
      - name: Ada Lovelace
        role: PI
        links:
          - icon: brands/github
            url: 'https://github.com/HugoBlox'
      - name: Charles Babbage
        role: Collaborator
  design:
    show_role: true
    show_social: true
    max_columns: 2

Preview

Team

Ada Lovelace

Charles Babbage

Collaborator

`portfolio`

Named collection + optional tag chips (`blox.js`). Tags from each page's `taxonomy.tag`.

Example

- block: portfolio
  content:
    title: Projects
    collection: pubs
    count: 3
    filters:
      tags:
        - all
        - software
        - paper
    archive:
      enable: true
      link: /publications/
      text: See all

Preview

Projects

An example preprint

A recent preprint to keep the publications list looking current.

An example journal article

A short abstract for an example journal article used by the portfolio demo fixture.

An example conference paper

An example conference paper for citation listings in the portfolio fixture.

See all

`map`

Interactive MapLibre + OpenFreeMap (no API key). Layouts: `side-by-side` (default) or `map-only`. Styles: `streets`, `light`, `dark`, `bright`.

Example

- block: map
  content:
    title: Visit the lab
    subtitle: Analytical Engines Lab
    location:
      lat: 51.5246
      lng: -0.1339
      address: |-
        Gower Street
        London WC1E 6BT
    zoom: 14
    cta:
      phone: +44 20 0000 0000
      email: ada@example.com
      directions:
        text: Get directions
  design:
    layout: side-by-side
    height: md
    style: streets

Preview

Visit the lab

Analytical Engines Lab

Gower StreetLondon WC1E 6BT
+44 20 0000 0000
ada@example.com

Get directions

`gallery`

Layouts: `grid`, `masonry`, `justified`, `carousel`, `slideshow`. Lightbox on by default (`design.lightbox: false` to disable). Optional `aspect_ratio`, `gap`, `caption_position`.

Example

- block: gallery
  content:
    title: Gallery
    items:
      - src: 'https://picsum.photos/seed/blox-docs-1/640/400'
        alt: Sample one
        caption: Sample image
        aspect_ratio: 1.6
      - src: 'https://picsum.photos/seed/blox-docs-2/640/800'
        alt: Sample two
        caption: Tall sample
        aspect_ratio: 0.8
      - src: 'https://picsum.photos/seed/blox-docs-3/640/400'
        alt: Sample three
        caption: Sample image
        aspect_ratio: 1.6
  design:
    layout: masonry
    columns: 3
    lightbox: true

Preview

Gallery

Shortcodes → MDX components

In .mdx content (not plain Markdown), use these components — markup matches upstream shortcodes. Visual samples below use the same CSS classes.

Callout

Note

Use for asides that should stand out from body copy.

Tip

Also: warning, danger, info, success, and the other Obsidian-compatible types.

<Callout type="tip" title="Optional title">
Helpful hint with **markdown** inside.
</Callout>

Button

<Button url="/publications/" style="primary" size="lg" icon="arrow-right">
Browse publications
</Button>

<Button url="https://hugoblox.com" style="outline" new_tab>
Upstream docs
</Button>

Styles: primary, outline, ghost, link. Sizes: sm, md, lg.

InlineIcon

Built with <InlineIcon name="brands/github" /> and Deno.

Icon names from the pruned set (~55): brands/github, brands/x, academicons/cv, heroicons like arrow-right, check-circle, etc. Unknown names fall back to text like upstream.

Spoiler

<Spoiler text="Click to reveal">
Hidden solution or aside.
</Spoiler>

Video / Audio

<Video src="/media/demo.mp4" controls />
<Audio src="/media/track.mp3" />

Not in this port

Deferred landing blocks: search-hero (Pagefind), help-categories / help-questions (Hugo help-center taxonomies).

Shortcodes not ported: cite, math, chart, notebook, slide, embed, card/cards, toc, and similar. See Adapting to Dune for the other platform gaps (Pagefind, BibTeX, docs layout).

Blocks and shortcodes

Landing blocks

resume-biography-3 (alias: biography)

Ada Lovelace

Professional Summary

Education

Interests

markdown

collection (alias: content-collection)

resume-experience (alias: experience)

Experience

Research Scientist

Education

Computer Science

resume-skills (alias: skills)

resume-awards (alias: awards)

Best Paper

resume-languages (alias: languages)

cta-card

Build your own academic site

Marketing & content blocks

hero

Landing blocks, ported

dev-hero

Ada Lovelace

features

Why blocks

Academic CV

Marketing

Collections

stats

Impact at a glance

120+

45

12

faq

FAQ

logos

steps

How it works

Install

Configure

Compose

Install

Configure

Compose

testimonials

What people say

pricing

Plans

Starter

Lab

comparison-table

Compared

focus-areas (alias: research-areas)

Research themes

Documentation systems

Open science

tech-stack

Tech stack

Runtime

Content

contact-info

Contact

Visit

Office Hours

Connect

Find me on

cta-button-list

cta-image-paragraph

Compose freely

team-showcase

Team

Ada Lovelace

Charles Babbage

portfolio

Projects

An example preprint

An example journal article

An example conference paper

`resume-biography-3` (alias: `biography`)

`markdown`

`collection` (alias: `content-collection`)

`resume-experience` (alias: `experience`)

`resume-skills` (alias: `skills`)

`resume-awards` (alias: `awards`)

`resume-languages` (alias: `languages`)

`cta-card`

`hero`

`dev-hero`

`features`

`stats`

`faq`

`logos`

`steps`

`testimonials`

`pricing`

`comparison-table`

`focus-areas` (alias: `research-areas`)

`tech-stack`

`contact-info`

`cta-button-list`

`cta-image-paragraph`

`team-showcase`

`portfolio`

`map`

`gallery`