EN

Collection List

A universal collection listing component that displays a grid of items with pagination support. Works with any collection (blog posts, components, products, etc.) and automatically detects available fields like author and date.

The grid below is a live instance of this component listing the blog collection. For an example including pagination see the blog page

Configuration

yaml
- sectionType: collection-list
  collectionName: 'blog'  # Required: name of collection to display
  containerTag: section  # section, article, or aside
  disabled: false
  id: ""
  classes: ""
  containerFields:
    inContainer: false
    isAnimated: true
    noMargin:
      top: true
      bottom: false
    noPadding:
      top: false
      bottom: false
    background:
      isDark: true
      color: ""
      image: ""
      imageScreen: "none"  # light, dark, none
  hasPagingParams: true
  pagingParams:
    numberOfBlogs: ""       # Total number of items (auto-populated)
    numberOfPages: ""       # Total pages needed (auto-populated)
    pageLength: ""          # Items per page (auto-populated)
    pageStart: ""           # Starting index for current page (auto-populated)
    pageNumber: ""          # Current page number (auto-populated)

Configuration Options

Collection Settings

PropertyTypeRequiredDescription
collectionNamestringYesName of the collection to display ('blog', 'components', 'products', etc.)

Pagination Settings

PropertyTypeRequiredDescription
hasPagingParamsbooleanNoEnables pagination functionality
pagingParams.numberOfBlogsstringNoTotal number of items (auto-populated)
pagingParams.numberOfPagesstringNoTotal pages needed (auto-populated)
pagingParams.pageLengthstringNoItems per page (auto-populated)
pagingParams.pageStartstringNoStarting index for current page (auto-populated)
pagingParams.pageNumberstringNoCurrent page number (auto-populated)

The component automatically includes author/date information if present in collection items.

Note: This component requires the metalsmith-sectioned-blog-pagination plugin to calculate and populate pagination parameters automatically.

Notes

About hasPagingParams

  1. Marks the target section: In templates with multiple sections, hasPagingParams: true identifies which specific section should receive the pagination metadata (page number, total pages, current list of posts).
  2. Validation requirement: The plugin requires at least one section with hasPagingParams: true in the main template file. If missing, it throws an error: "blog.md must contain a section with hasPagingParams: true" (src/index.js:50-51).
  3. Parameter injection point: When generating pagination pages, the plugin finds the section with hasPagingParams: true and injects the pagination parameters into that section's params object, including:
  • pageNumber: Current page number
  • numberOfPages: Total number of pages
  • currentList: Array of blog posts for the current page

This allows the plugin to work with modular page builders where content is organized in sections, ensuring pagination data goes to the correct section rather than being added globally.

Blog Post Data Structure

Each blog post in the collection needs a card object for the blog-list component to render properly:

yaml
# In individual blog post frontmatter
card:
  title: 'Architecture Philosophy'
  date: '2025-06-02'
  author:
    - Albert Einstein
    - Isaac Newton
  image: '/assets/images/sample9.jpg'
  featuredBlogpost: true
  featuredBlogpostOrder: 1
  excerpt: |-
  This starter embodies several key principles that make structured content management both powerful and approachable.

Option settings for the collections plugin determine the sort order of the cards. In metalsmith.js:

javascript
.use(
  collections( {
    blog: {
      pattern: 'blog/*.md',
      sortBy: 'card.date',
      reverse: false
    }
  } )
)