Installing Metalsmith Components

The Metalsmith Components library provides downloadable packages for all sections and partials. Each package includes everything you need to use the component in your project.

What's included in each package:

• Component template (.njk file)
• Styles (.css file, if applicable)
• JavaScript (.js file, if applicable)
• Manifest file with metadata and dependencies
• Configuration examples (.yaml file)
• Comprehensive README with usage instructions
• Automated installation script

Components are designed to work seamlessly with theMetalsmith2025 Structured Content Starter.

Customizing Component Paths

By default, components install to lib/layouts/components/sections/ and lib/layouts/components/_partials/. You can customize these paths by creating a metalsmith-components.config.json file in your project root:

{
  "componentsBasePath": "lib/layouts/components",
  "sectionsDir": "sections",
  "partialsDir": "_partials"
}

The install scripts automatically read this config file if present, giving you complete control over your project structure while maintaining convention-based defaults.

Every component package includes an automated installation script that handles the setup for you.

Installing an Individual Component

After downloading a component package, navigate to your Metalsmith project root directory (where your package.json file is located), extract the package there, and run the install script:

# Navigate to your Metalsmith project root
cd /path/to/your/metalsmith-project

# Extract the package in the project root
unzip ~/Downloads/hero.zip

# Navigate into the extracted component directory
cd hero

# Run the installation script
./install.sh

Important:Always extract component packages in your project root directory. The install script needs to be run from within the extracted component folder, but it will copy files to the correct locations (lib/layouts/components/sections/ or lib/layouts/components/_partials/) in your project.

After installation completes successfully, you can safely delete the extracted component folder (e.g., hero/) and the downloaded ZIP file.

The installation script will:

1. Verify you're in a Metalsmith project directory
2. Check for existing installations and compare versions
3. Validate that required dependencies are installed
4. Copy component files to the correct locations
5. Report any missing dependencies with download links

Example Installation Output

🔧 Installing hero v0.0.1...

Checking dependencies...
⚠ Warning: Missing required partials:
  • text
  • ctas
  • image

Download from: https://metalsmith-components.netlify.app/downloads/

Continue installation anyway? (y/n)

If you proceed, the component files will be installed even if dependencies are missing. You can download the required partials later.

Installing the Complete Bundle

The bundle includes a master installation script with two modes:full installandupdate-only.

Full Install (Default)

Install all components or update your existing subset:

# Navigate to your Metalsmith project root
cd /path/to/your/metalsmith-project

# Extract the bundle in the project root
unzip ~/Downloads/metalsmith-components.zip

# (Optional) Copy the sample config to customize component paths
cp metalsmith-components/metalsmith-components.config.json .

# Run the master installation script from project root
./metalsmith-components/install-all.sh

Important:Always run the install script from your project root directory. The script will automatically find the extracted components and install them to the correct locations based on your configuration.

If you already have components installed, the script will prompt you to choose:

• Install all components- Adds new components, updates existing ones (52 total)
• Update existing components only- Only updates components you already have (skips new ones)

Update-Only Mode

Only update components you're already using:

./metalsmith-components/install-all.sh --update-only
# or use the short form:
./metalsmith-components/install-all.sh -u

This mode is perfect for:

• Getting updates for the specific components you use
• Avoiding bloat from components you don't need
• Quick updates when new versions are released

The update-only mode detects installed components by checking for manifest.json files. Only components with matching names will be updated. For example, if you're using theMetalsmith2025 Structured Content Starter, approximately 22 components will be detected and updated.

Note: The bundle includes a sample metalsmith-components.config.json file. Copy it to your project root before installation if you want to customize where components are installed.

The install script automatically:

• Installs all partials first (resolving dependencies)
• Then installs all sections
• Reports which components were installed/updated and which were skipped
• Provides a summary of the installation

After installation completes, you can clean up:

# Remove the extracted bundle folder
rm -rf metalsmith-components

# Optionally remove the downloaded ZIP file
rm ~/Downloads/metalsmith-components.zip

Understanding and managing component dependencies ensures your components work correctly.

How Dependencies Work

Most section components depend on one or more partial components. For example, the hero section requires:

• text partial - for headings and prose content
• ctas partial - for call-to-action buttons
• image partial - for hero images
• commons partial - for shared utilities

These dependencies are automatically detected by the metalsmith-bundled-components plugin, which bundles only the CSS and JavaScript actually used on each page.

Checking Dependencies

Each component's manifest.json file lists its dependencies:

{
  "name": "hero",
  "requires": ["text", "ctas", "image", "commons"]
}

You can also check the README.md file included in each package for a complete list.

Installing Missing Dependencies

If you're missing required partials, the installation script will warn you and provide download links. You can:

1. Download individual partials from their reference pages
2. Use the complete bundle to get all partials at once
3. Continue without the dependency (component may not render correctly)

Version Compatibility

All components share the same version number as the main project. When downloading components, they'll work together seamlessly regardless of when you downloaded them.

However, the contentHash field in each manifest.json tracks actual changes to component files. This allows the install script to detect when a component has truly changed vs. just having a version bump.

Common issues and solutions when installing components.

Component Not Rendering

Problem:Component doesn't appear on the page after installation.

Solutions:

• Verify all required dependencies are installed
• Check that file paths are correct in your project structure
• Ensure your build process completed without errors
• Review the component's manifest.json for missing files

Build Errors

Problem:Build fails after installing a component.

Solutions:

• Check for YAML syntax errors in your frontmatter
• Verify the component's sectionType matches the component name
• Ensure all required fields are provided in your configuration
• Review build output for specific error messages

Missing Styles or Scripts

Problem:Component appears but styling or interactivity is missing.

Solutions:

• Verify the metalsmith-bundled-components plugin is configured
• Check that CSS/JS files exist in the component directory
• Ensure your build process includes PostCSS for CSS processing
• Clear your browser cache and rebuild

Version Conflicts

Problem:Install script reports version conflicts.

Solutions:

• Check the contentHash to see if files actually changed
• Review the component's README for breaking changes
• Consider downloading the complete bundle for consistency
• Backup your customizations before upgrading

Permission Errors

Problem:Install script fails with permission errors.

Solutions:

• Make the install script executable: chmod +x install.sh
• Run from your project root directory
• Ensure you have write permissions in the project directory

For additional help, visit theComponent Architectureguide or review the YAML to HTML documentation.