Page Features & Layouts

HugoBlox pages are frontmatter-driven. Use these switches to control how each page looks, what it shows, and how it behaves — without touching templates.

提示

This guide demonstrates how to use common features. For a complete dictionary of every available parameter (types, defaults, etc.), see the Front Matter Reference.

🖼️ Page Header & Cover

You have two options for page visuals: a Featured Image (standard blog style) or a Page Cover (Notion-style).

Image Guidelines

Optimized for high-resolution displays and responsive layouts.

• Formats: WebP (recommended) or JPG for photography. Use PNG for diagrams requiring lossless detail.
• SVG: Supported for vector diagrams but rendered as-is (bypassing Hugo’s resize pipeline).

Featured Image

Used for social sharing cards and article thumbnails.

• Dimensions: 1600×900 px (16:9 aspect ratio).
• Composition: Center the subject. Avoid text near edges to prevent cropping in summary cards.

Page Cover

Full-width header image.

• Dimensions: 2560×1100 px (~21:9 aspect ratio).
• Composition: Keep the focal point within the center 60% of the image for best mobile compatibility.

Option A: Page Cover (Notion-Style)

A full-width, immersive header with optional icon and effects.

Auto-Detection: Simply add an image named cover.jpg (or png/webp) to your page folder.

Configuration:

---
cover:
  image: "cover.jpg"      # Optional if using auto-detection
  style: "gradient"       # gradient | glass | blur | default
  icon:
    name: "📊"            # Emoji or icon name
  position:
    x: 50                 # Focus point X (0-100%)
    y: 50                 # Focus point Y (0-100%)
---

Styles

• gradient: Adds a subtle fade at the bottom (Default)
• glass: Modern frosted glass effect
• minimal: Shorter height, no effects

Option B: Featured Image

Standard image that appears in social previews and at the top of the article body.

---
image:
  filename: my-image.jpg  # in assets/media/ or page bundle
  focal_point: Smart      # Smart, Center, TopLeft, etc.
  preview_only: false     # true = social only, hide on page
  alt_text: "A description of the image"
---

注意

You can use both! The cover will appear as the header, and the image can be used for social sharing cards.

Use Page Bundles

For the best experience, use Page Bundles (folders named index.md). This allows you to keep images alongside your content.

• 文件夹content/

  • 文件夹post/

    • 文件夹my-amazing-post/

      • index.md # Your content
      • my-image.jpg # Your featured image

✍️ Metadata & Authors

Attribute content to authors, set publishing dates, and organize with tags.

---
title: My Post
summary: "Short teaser shown in lists"
date: 2023-10-01        # Published date
lastmod: 2023-10-05     # Updated date
authors:
  - admin               # references content/authors/admin/_index.md
  - Jane Doe            # plain text name
tags: [HugoBlox, Docs]
categories: [Tutorial]
featured: true          # Pin to the homepage/featured widget
---

🎨 Layout Options

Control the page structure: enable/disable the Table of Contents, sharing buttons, comments, and header styling.

---
share: true          # show sharing buttons
commentable: true    # enable comments (if configured in params.yaml)
toc: true            # show table of contents on the page

cover:
  image: ""          # cover image
---

🔗 Resources, Buttons & Slides

Attach downloads, add Call-to-Action (CTA) buttons to the header, or embed a slide deck.

---
# 1. Attach downloadable files
resources:
  - src: paper.pdf
    title: Read the paper

# 2. Add header buttons (CTAs)
links:
  - name: Code
    url: https://github.com/...
    icon: github
  - name: Demo
    url: https://...

# 3. Embed Slides
slides: my-talk   # Embeds content/slides/my-talk.md
---

注意

For Slides, create your presentation in content/slides/my-talk.md. The slides parameter simply references the filename (without extension).

🛠️ Advanced Rendering

Unlock powerful rendering features for technical content.

Math

Enable LaTeX math rendering using KaTeX:

math: true

Then use $E=mc^2$ for inline or $$...$$ for blocks.

Diagrams

Enable Mermaid diagrams:

diagram: true

Then use ````mermaid` code blocks.

Highlighting

Control code syntax highlighting languages:

highlight: true
highlight_languages: ["python", "go", "r"]

🌐 URLs & Visibility

Manage how your page is indexed and accessed.

---
draft: false                            # true = hide from production
weight: 10                              # Order in lists (lower = earlier)
aliases: ['/old-url/']                  # Redirects from old paths
canonical: 'https://example.com/new/'   # SEO canonical URL
---

🚀 Quick Recipes

Copy-paste these patterns to get started fast.

Blog Post

Standard blog post with engagement features.

title: My Post
subtitle: A clear subtitle
image:
  filename: featured.jpg
toc: true
share: true
commentable: true
tags: [News]

Research Paper

Academic paper with PDF and links.

title: My Paper
featured: true
resources:
  - src: paper.pdf
links:
  - name: Code
    url: https://github.com/...

Docs Page

Documentation with navigation.

title: Installation
toc: true
weight: 10
# comments/share often disabled
commentable: false
share: false

Talk / Event

Event page with slides.

title: My Conference Talk
date: 2023-11-15
slides: my-deck
links:
  - name: Video
    url: https://youtube.com/...