EN

What is the Eleventy Starter?

The Eleventy Structured Content Starter is a modern static website template that uses a component-based architecture. Unlike traditional static web sites that embed content in Markdown files, this starter defines pages using structured data in frontmatter.

The starter embraces a component-based architecture that lets you build pages by composing reusable sections. Rather than writing content in Markdown, you define everything as structured YAML data in frontmatter. The build system scans all components used across your entire site and bundles them into optimized, cacheable CSS and JavaScript files. There's no framework overhead—just pure HTML, CSS, and vanilla JavaScript rendered through the powerful Nunjucks templating engine.

This approach works beautifully for marketing websites, documentation sites, blogs, portfolios, landing pages, and any project that benefits from reusable, structured content. The starter comes with several pre-installed components and provides a solid foundation for adding more from the Nunjucks Components library.

Installation

Getting started with the Eleventy Starter is straightforward. You'll need Node.js 20 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/eleventy-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 Eleventy, plugins, and build tools.

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 Eleventy site ready for development.

Understanding the Project Structure

The starter follows a clear, organized structure that separates content, components, and configuration.

Key Directories

my-site/
├── src/                      # Source content files
│   ├── index.md              # Homepage
│   ├── about.md              # About page
│   ├── blog/                 # Blog posts
│   ├── _data/                # Global data (JSON files)
│   ├── _includes/            # Templates and components
│   │   ├── components/       # Reusable components
│   │   │   ├── sections/     # Page sections (hero, banner, etc.)
│   │   │   └── _partials/    # UI partials (text, ctas, image, etc.)
│   │   ├── icons/            # SVG icon templates
│   │   └── layouts/          # Page layout templates
│   └── assets/               # Images, fonts, global styles
├── lib/                      # Filters and plugins
│   ├── filters/              # Nunjucks filters
│   └── plugins/              # Eleventy plugins
├── _site/                    # Generated site (git-ignored)
├── eleventy.config.js        # Build configuration
└── package.json              # Project dependencies

Content Files (src/)

Your content lives in the src/ directory as Markdown files with YAML frontmatter. Each file represents a page on your site.

Components (src/_includes/components/)

The starter includes two types of components:

Sections - Large page building blocks like heroes, banners, and content sections. These are complete, self-contained page elements.

Partials - Smaller reusable UI elements like text blocks, CTAs, and images. Sections typically depend on multiple partials.

Assets (src/assets/)

Static assets like images, fonts, and global stylesheets. The build system automatically processes and optimizes these files.

Data Files (src/_data/)

Global data stored as JSON files (site metadata, navigation, author info, etc.) that can be referenced throughout your templates.

Build Output (_site/)

The generated static site. This directory is created during builds and is excluded from version control. Deploy this directory to your hosting service.

Creating Your First Page

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: layouts/sections.njk

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

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

  - component: text-only
    container: article
    data:
      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.

Development Workflow

The starter includes several npm scripts to streamline your development workflow.

Core Commands

Development server with live reload:

npm start

Starts the development server at http://localhost:3000 with file watching and automatic browser refresh.

Production build:

npm run build

Creates an optimized production build in the _site/ directory with minified CSS and JavaScript.

Run Eleventy without server:

npm run dev

Builds the site once without starting the development server.

Clean build output:

npm run clean

Removes the _site/ directory to start fresh.

Debug mode:

npm run debug

Runs Eleventy with verbose debug output for troubleshooting.

Typical Development Session

  1. Start the development server: npm start
  2. Edit files in src/
  3. View changes automatically in browser
  4. Build for production: npm run build
  5. Deploy the _site/ directory

File Watching

The development server watches these locations:

  • src/**/* - Content files and templates
  • src/assets/**/* - Static assets

Changes to these files trigger automatic rebuilds and browser refresh.

Adding More Components

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

Pre-installed Components

The starter includes these essential components:

Sections(17 components):

  • banner- Full-width banner with background
  • blog-author- Author information display
  • blog-list- List of blog posts
  • collection-links- Previous/next post links
  • collection-list- Generic collection display
  • commons- Shared section utilities
  • composed- Flexible multi-column layout
  • featured-posts- Highlighted blog posts
  • flip-cards- Interactive flip card grid
  • footer- Site footer
  • header- Site header with navigation
  • hero- Hero sections with images and CTAs
  • logos-list- Logo showcase
  • media-image- Image with optional caption
  • slider- Image/content carousel
  • testimonial- Quote/testimonial display
  • text-only- Markdown text content

Partials(16 components):

  • author-date- Author and date display
  • branding- Site branding/logo
  • breadcrumbs- Navigation breadcrumbs
  • button- Button element
  • card- Card component
  • collection-card- Collection item card
  • collection-pagination- Pagination controls
  • ctas- Call-to-action buttons
  • flip-card- Individual flip card
  • icon- SVG icon wrapper
  • image- Responsive images
  • logo- Logo display
  • navigation- Navigation menu
  • slider-pagination- Slider controls
  • text- Text block
  • text-link- Text with link

Adding New Components

To add components from the library:

Prerequisite: Configuration File

The starter includes a nunjucks-components.config.json file:

{
  "componentsBasePath": "src/_includes/components",
  "sectionsDir": "sections",
  "partialsDir": "_partials"
}

This tells the install scripts where to place component files.

Option 1: Download Individual Components

  1. Browse thesections libraryor 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
cd /path/to/your/project

# Extract the bundle
unzip ~/Downloads/nunjucks-components.zip

# Run the install script from project root
./nunjucks-components/install-all.sh

The script offers two modes:

  • Full install - Installs all 52 components
  • Update-only - Only updates components you already have

For detailed installation instructions, see Installing Nunjucks 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:
  - component: maps
    container: section
    data:
      mapProvider: 'leaflet'
      markers: 'office-locations'

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

Customizing Your Site

Make the starter your own by customizing styling, metadata, and configuration. For more inspiration you may want to checkout how we built this very website.

Site Metadata

Update site information in src/_data/site.json:

{
  "name": "My Awesome Site",
  "description": "Building amazing things with Eleventy",
  "url": "https://mysite.com",
  "author": "Your Name",
  "email": "you@mysite.com"
}

This data is available throughout your templates and used for SEO metadata.

Styling and Design Tokens

Global styles are in src/assets/styles/:

Design tokens (_design-tokens.css):

:root {
  /* Colors */
  --color-primary: #007bff;
  --color-secondary: #6c757d;

  /* Typography */
  --font-family-base: system-ui, sans-serif;
  --font-size-base: 1rem;

  /* Spacing */
  --spacing-unit: 1rem;
}

Edit these variables to customize colors, typography, and spacing throughout your site.

Base styles (_css-base.css): Global element styles, resets, and utilities.

Component Styles

Each component has its own CSS file that's automatically bundled when the component is used. Edit component styles directly in their directories:

src/_includes/components/sections/hero/hero.css

Build Configuration

Customize the build process in eleventy.config.js:

  • Add or remove plugins
  • Configure plugin options
  • Add custom filters
  • Modify directory structure

Adding Custom Filters

Create filter files in lib/filters/ and export them from lib/filters/index.js. Filters are automatically registered with Eleventy.

Deploying Your Site

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: _site
  5. Click "Deploy site"

Via Netlify CLI:

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

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: _site
  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: _site
  5. Click "Save and Deploy"

GitHub Pages

For GitHub Pages deployment:

  1. Add a GitHub Actions workflow (.github/workflows/deploy.yml):

    name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

  2. Enable GitHub Pages in repository settings, selecting "GitHub Actions" as the source

Custom Server

Deploy the _site/ directory to any static file server:

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

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

Next Steps

You now have a fully functional Eleventy site. Here are some resources to continue your journey:

Learn the Architecture

Expand Your Component Library

Advanced Topics

Get Help

Share Your Work

Built something with the starter? We'd love to see it! Share your projects and help inspire others in the community.

View on GitHub Browse Components