how to create a eleventy theme

Creating a theme for Eleventy (11ty), a simple yet powerful static site generator, involves organizing your files and directories, setting up template files, and writing styles and scripts. Here’s a step-by-step guide to help you create an Eleventy theme from scratch:

Step-by-Step Guide to Creating an Eleventy Theme

1. Install Eleventy

First, ensure you have Node.js installed. Then, you can install Eleventy globally via npm:

npm install -g @11ty/eleventy

Alternatively, you can add Eleventy as a development dependency in your project:

npm init -y
npm install @11ty/eleventy --save-dev

2. Set Up Your Project Directory

Create a new directory for your project and navigate into it:

mkdir my-eleventy-site
cd my-eleventy-site

3. Create Your Directory Structure

Set up the following directory structure:

my-eleventy-site/
├── src/
│   ├── _includes/
│   │   ├── layouts/
│   │   │   └── base.njk
│   │   ├── partials/
│   │   │   ├── header.njk
│   │   │   └── footer.njk
│   ├── index.md
│   └── about.md
├── .eleventy.js
├── package.json
└── .gitignore

4. Create a Basic Configuration File

Create the .eleventy.js configuration file in the root of your project:

module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "src",
      includes: "_includes",
      output: "_site"
    }
  };
};

5. Set Up Layouts and Partials

`src/_includes/layouts/base.njk`

This is the base layout for your site.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ title }}</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  {% include "partials/header.njk" %}
  <main>
    {{ content | safe }}
  </main>
  {% include "partials/footer.njk" %}
</body>
</html>

`src/_includes/partials/header.njk`

Your site’s header.

<header>
  <nav>
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about/">About</a></li>
    </ul>
  </nav>
</header>

`src/_includes/partials/footer.njk`

Your site’s footer.

<footer>
  <p>&copy; {{ "now" | date: "%Y" }} Your Site Name</p>
</footer>

6. Create Content Pages

`src/index.md`

Create your homepage with front matter.

---
layout: layouts/base.njk
title: Home
---
# Welcome to My Site

This is the homepage of my Eleventy site.

`src/about.md`

Create an about page.

---
layout: layouts/base.njk
title: About
---
# About Us

This is the about page of my Eleventy site.

7. Add Static Assets

Create a directory for your CSS and add your styles. For example, create a styles.css file:

my-eleventy-site/
├── src/
│   ├── css/
│   │   └── styles.css

Add some basic styles in src/css/styles.css:

body {
  font-family: Arial, sans-serif;
  line-height: 1.6;
  margin: 0;
  padding: 0;
}

header, footer {
  background: #333;
  color: #fff;
  padding: 1em;
}

nav ul {
  list-style: none;
  padding: 0;
}

nav ul li {
  display: inline;
  margin-right: 1em;
}

nav ul li a {
  color: #fff;
  text-decoration: none;
}

main {
  padding: 1em;
}

Update your .eleventy.js to copy static assets:

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("src/css");
  
  return {
    dir: {
      input: "src",
      includes: "_includes",
      output: "_site"
    }
  };
};

8. Build and Test Your Site

Run Eleventy to build your site:

npx eleventy

To start a local development server with live reloading, run:

npx eleventy --serve

Open your browser and navigate to http://localhost:8080 to see your site.

Conclusion

By following these steps, you can create a basic Eleventy theme with layouts, partials, and static assets. From here, you can continue to expand and customize your theme to meet your needs, adding more pages, custom shortcodes, and advanced templating features.