Section Anatomy

On this page we'll dissect the hero component from the Metalsmith2025 Structured Content Starter to understand how modern component-based architecture works in practice.

The shift from document-oriented to component-oriented content isn't just a technical change—it's a fundamental rethinking of how we build websites. The structured content starter makes this shift practical, providing a complete foundation for building modern sites without modern complexity.

Understanding the Component System

Before examining specific components, it's important to understand how Metalsmith processes these configurations. Each section component consists of two essential parts:

Configuration (YAML): Defines the content, structure, and presentation settings for a component instance. This is what content editors work with.

Template (Nunjucks/Handlebars): Renders the configuration into HTML. Templates interpret the configuration properties to generate the final markup.

The build pipeline reads your YAML configuration, passes it to the appropriate template based on the sectionType, and outputs rendered HTML. This separation allows you to modify content without touching code, and update templates without affecting content.

Hero Section Example

Let's examine a real Hero section configuration to understand how components work:

- sectionType: hero
  containerTag: section
  classes: 'first-section'
  id: ''
  description: 'This is a hero section'
  isDisabled: false
  isFullScreen: false
  isReverse: true
  containerFields:
    inContainer: false
    isAnimated: true
    noMargin:
      top: true
      bottom: true
    noPadding:
      top: false
      bottom: false
    background:
      isDark: true
      color: ''
      image: '/assets/images/sample12.jpg'
      imageScreen: 'dark' # light, dark, none
  text:
    leadIn: 'Metalsmith Components'
    title: Section Anatomy
    titleTag: 'h1'
    subTitle: 'A component-based approach provides significant advantages over monolithic templates. '
    prose: Components are independent unit with their own templates and configuration schema, enabling development, testing, and maintenance in isolation.
  ctas:
    - url: ''
      label: ''
      isButton: false
      buttonStyle: 'primary'
  image:
    src: ''
    alt: ''
    caption: ''

This configuration describes the hero section displayed at the top of this page. The hero features a background image overlaid with a dark screen for text readability, with white text that remains legible against the darkened background. The section stretches the full width of the viewport while the content remains constrained to a readable width.

Component Property Categories

The Hero section structure divides into three logical categories, each serving a specific purpose in the component system:

1. General Section Properties

These properties control the fundamental behavior and identity of the section:

Core Properties:

Control Properties:

2. Container Properties

Container properties manage the section's visual presentation and spacing behavior:

Layout Control:

Spacing Control:

The margin and padding objects provide granular control over section spacing:

Background Treatment:

The background object creates rich visual layers:

3. Functional Properties

These properties contain the actual content that users see:

Text Component:

The text object structures your written content hierarchically:

Call-to-Action (CTA) Component:

The CTA array enables multiple action buttons or links:

Image Component:

The image object handles visual media:

How Components Compose Pages

Sections stack vertically to create complete pages. The configuration order determines the rendering order. For example, a typical landing page might consist of:

1. Hero section (dramatic introduction)
2. Content section (key benefits)
3. Gallery section (visual proof)
4. CTA section (conversion focus)
5. Footer section (navigation and legal)

Each section operates independently, allowing you to reorder, add, or remove sections without affecting others. This modularity enables rapid iteration and A/B testing of page layouts.

Property Interactions and Cascading

Understanding how properties interact helps you create cohesive designs:

Visual Hierarchy: The titleTag property affects SEO and accessibility. Use only one h1 per page, typically in your hero section. Subsequent sections should use h2 for main headings.

Spacing Rhythm: Combine margin and padding controls to create visual rhythm. For example, remove bottom margin from a hero and top margin from the following section to create a connected flow.

Background Layering: When using both color and image properties, the color acts as a fallback while the image loads, preventing layout shift.

Responsive Behavior: The isReverse property typically applies only on larger screens. On mobile devices, sections often stack vertically regardless of this setting.

Best Practices for Component Configuration

Accessibility First: Always provide meaningful alt text for images and use semantic HTML tags appropriately. The titleTag should reflect the document

Performance Considerations: Reference optimized images in your background and image properties. Large background images should be compressed and properly sized for web delivery.

Content Strategy: Use leadIn text to provide context, especially when sections might be viewed independently (through deep linking or search results).

Maintainability: Use the description field to document the section's purpose, especially for complex layouts or when multiple team members edit content.

This component-based approach transforms how we think about web pages—from monolithic documents to composable, reusable sections that adapt to changing content needs while maintaining consistent quality and performance.