Simple Accordion Section

An interactive accordion component for displaying frequently asked questions or any collapsible content. Features smooth animations, accessibility support, and flexible data loading from JSON files.

Example 1

All FAQs

This example shows all available FAQs from the data source with a background color. The first accordion id open by default. Open a new accordion will close the old one.

How do I get started with Metalsmith Components?

Start by cloning the repository and running npm install to install dependencies. Then use npm start to launch the development server. The component library will be available at http://localhost:3000, where you can explore all available components and their documentation.

What is the structure of a component?

Each component contains several key files: a .yml file with frontmatter examples, a .njk Nunjucks template for markup, optional .css for component-specific styles, optional .js for interactive behavior, a manifest.json for dependencies and metadata, and an optional README.md for documentation.

How does the automatic bundling work?

The metalsmith-bundled-components plugin automatically scans pages to identify which components are used, then bundles only the required CSS and JavaScript for optimal performance. It applies PostCSS processing for autoprefixing and minification, generating per-page assets with no unused code.

Can I create custom components?

Yes! Follow the established component structure: create a new folder in either lib/layouts/components/_partials/ for small UI elements or lib/layouts/components/sections/ for large page sections. Include the necessary files (template, manifest, optional styles and scripts) and ensure your component follows the project's conventions for semantic HTML and accessibility.

How do I test my components?

Use the comprehensive Mocha test suite by running npm test. When adding new components, ensure you add test cases for the component's manifest, test with various configuration options, verify the component renders without errors, test responsive behavior and accessibility, and validate against the Metalsmith2025 Starter structure.

Example 2

Selected FAQs

Curated Content

This example shows only selected FAQs, allows multiple items to be expanded, and has no background color. Note the OPEN/CLOSE ALL link above the first accordion.

Open All

How do I get started with Metalsmith Components?

What is the structure of a component?

Can I create custom components?

Implementation Notes

Data Structure

For our examples, FAQ data files are stored in lib/data/faqs/ as JSON files. Each FAQ file should have the following structure:

{
  "id": "unique-id",
  "question": "Your question here?",
  "answer": "Your detailed answer here."
}

JavaScript Functionality

The accordion JavaScript handles:

Click events on accordion headers
Expanding/collapsing panels with proper ARIA attributes
Single or multiple item expansion based on configuration
Initial state management (expand first item if configured)

Styling

The component includes responsive styles with:

Smooth CSS transitions for expand/collapse animations
Hover and focus states for accessibility
Customizable through CSS variables

Configuration

faqs:
  scope: "all"
  source: "faqs"
  selections:
    - "getting-started"
    - "component-structure"
expandIndex: 0
allowMultiple: false

Notes

Load all FAQs or select specific ones by ID
Control expand behavior and multiple item expansion
Full keyboard navigation and screen reader support
CSS-based transitions for expand/collapse

Property	Type	Description
`faqs.scope`	string	"all" or "selections" - determines data loading
`faqs.source`	string	data source in lib/data/ (e.g., "faqs")
`faqs.selections`	array	array of IDs when scope is "selections"
`expandIndex`	number	index of item to expand by default (0-based)
`allowMultiple`	boolean	allow multiple expanded items