Getting Started with the Metalsmith2025 Starter

Getting started with the Metalsmith2025 Starter is straightforward. You'll need Node.js 18 or higher installed on your system.

Clone the Repository

Start by cloning the starter repository to your local machine:

git clone https://github.com/wernerglinka/metalsmith2025-structured-content-starter my-site

This creates a new directory called my-site with all the starter files. You can replace my-site with any name you prefer for your project.

Install Dependencies

Navigate to your project directory and install the required dependencies:

cd my-site
npm install

This installs all the necessary packages including Metalsmith, plugins, and build tools. The installation typically takes 1-2 minutes depending on your connection speed.

Start the Development Server

Launch the development server with live reload:

npm start

Your site is now running at http://localhost:3000. The browser will automatically refresh whenever you make changes to your files.

That's it! You now have a fully functional Metalsmith site ready for development.

Let's create a new page to understand how the structured content approach works.

Create a New Page File

Create a new file in the src/ directory:

touch src/services.md

Define Page Structure in Frontmatter

Add content to services.md using structured frontmatter:

---
layout: pages/sections.njk

seo:
  title: Our Services
  description: 'Professional services for modern businesses'

sections:
  - sectionType: hero
    containerTag: section
    containerFields:
      background:
        image: '/assets/images/services-hero.jpg'
        imageScreen: 'dark'
    text:
      title: 'Our Services'
      prose: 'Comprehensive solutions for your business needs'
    ctas:
      - url: '#services'
        label: 'Learn More'
        isButton: true

  - sectionType: text-only
    containerTag: article
    containerFields:
      inContainer: true
    text:
      title: 'What We Offer'
      prose: |
        We provide expert consulting and development services
        to help businesses thrive in the digital age.
---

View Your New Page

Save the file and visit http://localhost:3000/services/ in your browser. The page is automatically generated with:

• A hero section with background image
• A text section with content
• Proper HTML structure and styling
• SEO metadata

Key points:

• No Markdown body content needed
• Everything defined in structured YAML
• Components automatically rendered from frontmatter
• Changes appear instantly in the browser

For more details, seeBuilding Pages with Components.

The starter includes a basic set of components. You can easily add more from the Metalsmith Components library.

Pre-installed Components

The starter includes these essential components:

• hero - Hero sections with images and CTAs
• banner - Content banners with media
• text-only - Text content sections
• media - Image and video sections
• text partial - Headings and prose content
• ctas partial - Call-to-action buttons
• image partial - Responsive images

Adding New Components

To add components from the library:

Option 1: Download Individual Components

1. Browse the sections library or partials library
2. Click the download button on any component page
3. Extract and run the install script:

   unzip maps.zip
   cd maps
   ./install.sh
   

Option 2: Download the Complete Bundle

Get all components at once:

1. Download the complete bundle
2. Extract and run the master install script from your project root:

   # Navigate to your project root (where package.json is)
   cd /path/to/your/metalsmith-project
   
   # Extract the bundle
   unzip ~/Downloads/metalsmith-components.zip
   
   # Run the install script from project root
   ./metalsmith-components/install-all.sh
   

The script offers two modes:

• Full install - Installs all 52 components
• Update-only - Only updates components you already have (22 components in the starter)

For detailed installation instructions, see Installing Metalsmith Components.

Using Installed Components

Once installed, components are immediately available for use in your pages. Simply add them to the sections array in your frontmatter:

sections:
  - sectionType: maps
    containerFields:
      inContainer: true
    mapProvider: 'leaflet'
    markers: 'office-locations'

The build system automatically bundles the required CSS and JavaScript for components used on each page.

The starter works with all major static hosting services. Here's how to deploy to popular platforms.

Netlify

Via Git Integration:

1. Push your project to GitHub, GitLab, or Bitbucket
2. In Netlify, click "New site from Git"
3. Connect your repository
4. Set build settings:
   • Build command: npm run build
   • Publish directory: build
5. Click "Deploy site"

Via Netlify CLI:

npm install -g netlify-cli
npm run build
netlify deploy --prod --dir=build

Vercel

Via Git Integration:

1. Push your project to GitHub, GitLab, or Bitbucket
2. Import your repository in Vercel
3. Vercel auto-detects settings:
   • Build command: npm run build
   • Output directory: build
4. Click "Deploy"

Via Vercel CLI:

npm install -g vercel
npm run build
vercel --prod

Cloudflare Pages

1. Push your project to GitHub or GitLab
2. In Cloudflare Pages, click "Create a project"
3. Connect your repository
4. Set build configuration:
   • Build command: npm run build
   • Build output directory: build
5. Click "Save and Deploy"

GitHub Pages

For GitHub Pages deployment to a subdirectory:

1. Set the BASE_PATH environment variable:

   BASE_PATH=/my-repo npm run build
   

2. Deploy the build/ directory to the gh-pages branch

The metalsmith-safe-links plugin automatically handles relative URLs for subdirectory deployments.

Custom Server

Deploy the build/ directory to any static file server:

npm run build
rsync -avz build/ user@server:/var/www/html/

Your site is pure HTML, CSS, and JavaScript with no server-side requirements.