Introduction

PaloPageHeader is Palo’s page-level hero for list pages (Blog, Portfolio), static pages (Contact, Sitemap), and MDX/Markdown pages via frontmatter. It renders a semantic <section> with a configurable heading, optional HTML subtitle, and optional background media.

PaloPageHeader 是 Palo 的页面级头部组件，用于列表页（Blog、Portfolio）、静态页（Contact、Sitemap）以及通过 frontmatter 配置的 MDX/Markdown 页面。它输出语义化 <section>，包含可配置的标题、可选 HTML 副标题和背景媒体。

Component path: src/components/PaloPageHeader.astro

Quick Start

---
import PaloPageHeader from '@components/PaloPageHeader.astro'
---

<PaloPageHeader
  title="Blog"
  subtitle="Latest news and updates"
/>

Global defaults live in config.yaml → components.paloPageHeader. Any prop left empty ('') or omitted falls back to those defaults.

全局默认值在 config.yaml → components.paloPageHeader。留空（''）或未传入的 prop 会回退到 config 默认值。

See Config: Everything You Like for the full paloPageHeader block.

Where It Appears

Parameters

bg object

<PaloPageHeader
  title="Nature"
  subtitle="Exploring the outdoors"
  contentColor="#ffffff"
  topNavigationTheme="dark"
  bg={{
    image: '/branding/hero-bg.png',
    fixed: false,
    overlayOpacity: 0.4,
  }}
/>

Note: Background props are nested under bg, not flat on the component root.

注意： 背景相关 prop 嵌套在 bg 对象内，不是组件根级的平铺 prop。

Title & Subtitle

The title renders through accessible-astro-components Heading at headingLevel (default h1).

<PaloPageHeader
  title="Our Services"
  subtitle="Check out our <strong>amazing features</strong> and <a href='/contact'>contact us</a>"
  descClass="text-lg text-neutral-600"
/>

Subtitle HTML is sanitized — allowed tags: b, i, em, strong, a, span, br. Links support href, title, target, rel.

副标题 HTML 经 sanitize 过滤——允许 b、i、em、strong、a、span、br。

Display Mode (fullscreen)

<PaloPageHeader
  title="Welcome"
  subtitle="We're glad you're here"
  fullscreen={true}
  alignV="center"
/>

Standard mode automatically adds top padding: nav min-height + page-header-padding-block, so content clears the fixed header.

标准模式自动添加顶部内边距（导航栏高度 + padding-block），内容不会被固定顶栏遮挡。

Alignment (alignV / alignH)

alignV controls vertical grid alignment; alignH controls both text-align and flex cross-axis alignment.

<PaloPageHeader
  title="Center Aligned"
  subtitle="Title and subtitle centered"
  fullscreen={true}
  alignV="center"
  alignH="center"
/>

There is no separate textAlign prop — use alignH.

没有独立的 textAlign prop——用 alignH 控制。

Background Media

Image

Background images render via ContentImage with progressive loading:

• Non-PNG: dominant-color placeholder while loading, then fades out
• PNG: no color placeholder (preserves transparency)

<PaloPageHeader
  title="City Life"
  subtitle="Urban adventures"
  contentColor="#ffffff"
  bg={{
    image: '/branding/hero-bg.png',
    overlayOpacity: 0.5,
  }}
  topNavigationTheme="dark"
/>

Video

Videos autoplay muted, loop, with playsinline. Always pair with overlayOpacity for text contrast.

<PaloPageHeader
  title="Innovation"
  subtitle="Forward-thinking solutions"
  contentColor="#ffffff"
  bg={{
    video: '/videos/hero.mp4',
    overlayOpacity: 0.5,
  }}
/>

Solid Color

<PaloPageHeader
  title="Design"
  subtitle="Creating beautiful experiences"
  bg={{ color: '#3b82f6' }}
  contentColor="#ffffff"
/>

Fixed Background (bg.fixed)

When bg.fixed: true, the background media is position: fixed covering the viewport. Dividers repaint as pseudo-elements above the fixed layer.

<PaloPageHeader
  title="Parallax Header"
  subtitle="Background stays fixed while scrolling"
  fullscreen={true}
  bg={{
    image: '/branding/hero-bg.png',
    fixed: true,
    overlayOpacity: 0.6,
  }}
  contentColor="#ffffff"
/>

Navigation Theme (topNavigationTheme)

Sets data-top-navigation-theme on the section, which drives:

• Site header logo variant (light/dark)
• Button colors inside the page header (filled + outlined)

Explicit bg.color / contentColor always override the auto values.

显式传入 bg.color / contentColor 会覆盖自动推导的颜色。

<PaloPageHeader
  title="Dark Header"
  subtitle="Light navigation on dark background"
  topNavigationTheme="dark"
/>

Pass hasHero={true} on DefaultLayout when using a themed header so the layout coordinates nav styling.

使用主题头部时，在 DefaultLayout 上传 hasHero={true}，让布局协调导航样式。

Dividers (divider)

<PaloPageHeader title="Blog Post" subtitle="With top divider" divider="top" />
<PaloPageHeader title="Docs" subtitle="Bordered both sides" divider="both" />
<PaloPageHeader title="Clean" subtitle="No borders" divider="none" />

Container (useContainer)

<PaloPageHeader
  title="Full Width"
  subtitle="Edge-to-edge content area"
  useContainer={false}
/>

Padding & Custom Classes

There is no padding prop. Control spacing two ways:

没有 padding prop。两种方式控制间距：

1. class on root — Tailwind utilities override defaults (they sit in @layer utilities, above base padding):

<PaloPageHeader
  title="Compact"
  subtitle="Less vertical space"
  class="py-8"
/>

2. CSS variable — set --page-header-padding-block on the section or in config.yaml class.

Default padding uses --nav-min-height (static, no JS) so the first paint already clears the header.

Config Defaults (config.yaml)

components:
  paloPageHeader:
    headingLevel: "h1"
    descClass: "text-lg"
    alignV: "center"
    alignH: "left"
    divider: "bottom"
    useContainer: true
    fullscreen: false
    topNavigationTheme: ""
    class: ""

List pages (Blog, Portfolio) spread {...pageHeader} built from these defaults. Static pages like Contact pass '' for each prop to inherit config without hardcoding.

列表页从 config 构建 {...pageHeader} 并 spread。Contact 等静态页传 '' 继承 config，无需硬编码。

MDX / Markdown Frontmatter

Pages using MarkdownLayout can define a pageHeader block:

---
title: My Page
description: Page description
pageHeader:
  title: Custom Header Title
  subtitle: "Optional <strong>HTML</strong> subtitle"
  fullscreen: false
  alignV: center
  alignH: left
  divider: bottom
  contentColor: ""
  topNavigationTheme: dark
  useContainer: true
  bg:
    image: /branding/hero-bg.png
    video: ""
    color: ""
    fixed: false
    overlayOpacity: 0.4
---

When pageHeader is present, DefaultLayout receives hasHero={true} and the layout title comes from pageHeader.title (falls back to title).

Production Examples

Blog List Page (current Palo pattern)

<PaloPageHeader
  title={pageConfig.title}
  subtitle={pageConfig.subtitle}
  alignV="center"
  alignH="left"
  divider="bottom"
  bg={{ image: '', video: '', color: '', fixed: false, overlayOpacity: 0 }}
/>

Contact Page (inherit all config defaults)

<PaloPageHeader
  title="Contact"
  subtitle="Have a question? Get in touch with us!"
  fullscreen=""
  contentColor=""
  topNavigationTheme=""
  alignV=""
  alignH=""
  useContainer=""
  divider=""
  bg={{ image: "", color: "", fixed: false, overlayOpacity: 0 }}
/>

Empty strings trigger resolveStringProp → config.yaml defaults.

空字符串触发 resolveStringProp → 回退到 config.yaml 默认值。

Image Hero with Overlay

<PaloPageHeader
  title="The Future of Web Design"
  subtitle="Trends and innovations for 2026 and beyond"
  fullscreen={true}
  alignV="bottom"
  alignH="center"
  contentColor="#ffffff"
  topNavigationTheme="dark"
  divider="bottom"
  bg={{
    image: '/branding/hero-bg.png',
    overlayOpacity: 0.5,
  }}
/>

Tips

1. Use bg object — don’t use legacy flat props like backgroundImage (removed)

2. Set topNavigationTheme when using dark/light backgrounds so the site header logo stays readable

3. Always add overlayOpacity on photo/video backgrounds for WCAG contrast

4. Use alignH="center" for dramatic landing headers; left for list/index pages

5. Override padding via class="py-*" — not a dedicated padding prop

6. No slot — put CTA buttons in the section below PaloPageHeader, not inside it

7. 使用 bg 对象 — 不要用已废弃的平铺 prop（如 backgroundImage）

8. 深色/浅色背景时设置 topNavigationTheme — 保证顶栏 Logo 可读

9. 图片/视频背景务必加 overlayOpacity — 保证文字对比度

10. 着陆页用 alignH="center"；列表页用 left

11. 通过 class="py-*" 覆盖 padding — 没有专用 padding prop

12. 无 slot — CTA 按钮放在 PaloPageHeader 下方的 section 中

Accessibility

Place the primary page <h1> here on list/static pages. Detail pages (blog posts, projects) use PostHeader instead with headingLevel: h2 from config.

列表页/静态页的主 <h1> 应放在此处。详情页（文章、项目）使用 PostHeader，config 中默认 headingLevel: h2。

Conclusion

PaloPageHeader is the standard page opener across Palo: one component, config-driven defaults, nested bg for media, and topNavigationTheme for header coordination. Use it on list and static pages; use PostHeader for content detail pages with cover images.

PaloPageHeader 是 Palo 的标准页面头部：单一组件、config 驱动默认值、嵌套 bg 管理媒体、topNavigationTheme 协调顶栏。列表页和静态页用它；带封面的内容详情页用 PostHeader。