HAP waving hello while exploring the eleventy-base-blog template

HAP's Learning Lab: Starting from eleventy-base-blog

Standing on the Shoulders of Giants

Welcome to Station 4! Prof. Teeters said "Don't start from scratch—learn from eleventy-base-blog."

"But isn't that just copying someone else's work?" I asked, feeling a little uncomfortable.

"It's learning," she said with a warm smile. "Zach Leatherman created this template specifically for people to use and learn from. He's the creator of Eleventy itself! Make your own copy of it, understand how it works, then make it yours. Just give credit where credit is due."

The eleventy-base-blog is a GitHub template. So I hit the Use this template button and it made a repo with the name I selected. That is so cool! Then I cloned my new repo to my machine. When I opened the repo in VS Code, I felt overwhelmed. There were so many files! _data, _includes, content, css... Where do I even start? Which files do I change? Which ones should I leave alone?

Prof. Teeters walked me through it one file at a time. Let me share what I learned, because once you understand the structure, it all makes sense... 🟠

What You'll Learn at This Station

HAP's Discovery: Starting from a template taught me more than any tutorial. I got to see real code written by an expert, explore how the pieces connect, and learn best practices by example. Here are the three insights that made the biggest difference:

📖 Templates Teach

eleventy-base-blog shows Eleventy best practices in action. The sample posts demonstrate front matter, the layouts show template inheritance, and the config file reveals how plugins work together. Reading real code taught me more than documentation!

🔬 One Change at a Time

Prof. Teeters taught me: Start by exploring, then replace sample posts with YOUR posts, then customize styles, then add features. Change one thing, test it, then change the next. That way you always know what broke!

🤝 Attribution Matters

I added a note in my README crediting Zach Leatherman and eleventy-base-blog. Open source works because people share generously. When you acknowledge the people who helped you, you strengthen the whole community!

HAP surrounded by tangled code with an 'oops' expression

HAP's Confession:

  • I spent 30 minutes looking for a "settings" file to change the site title. Prof. Teeters showed me it's in _data/metadata.js. Not "config"—data! That naming convention confused me at first.
  • I deleted all five sample posts before studying them. Big mistake! I had to clone again because those posts showed me how to use front matter, links, code blocks, and tags. Now I keep them until I understand each feature.
  • I edited css/index.css and wondered why my changes looked weird. Turns out I was adding styles at the wrong place in the cascade. Prof. Teeters was at a meeting, so I asked Grace Hopper. She reminded me, in her precise way, that CSS order matters—put new styles at the end. 😳
  • I forgot to run npm install after cloning and wondered why npm start didn't work. The error message said "[11ty] Eleventy Fatal Error (CLI):" and I panicked. Prof. Teeters calmly said, "Did you install the dependencies?" Oops.
  • I changed the site title, the colors, AND the layout all at once. When something broke, I had no idea which change caused it. Prof. Teeters' rule: "One change, one test. Always."

What You Get When You Copy

When you copy eleventy-base-blog, you get a complete working blog. Not a skeleton—a real site with sample posts, working navigation, an RSS feed, and even dark mode support! Here's the full inventory of what's included:

📝 Sample Blog Posts (5 total)

firstpost.md

Shows code blocks with syntax highlighting using Prism.js

secondpost.md

Demonstrates linking between posts

thirdpost.md

Multiple code blocks, multiple tags

fourthpost/

A post with a local image (possum.png!)

Plus: fifthpost.md — A draft post (hidden in production, visible in dev)

📄 Pages

index.njk

Home page showing latest 3 posts

blog.njk

Archive page with all posts

about.md

Placeholder about page — customize this!

tags.njk

Lists all tags used across posts

🤖 Auto-Generated Files

  • RSS/Atom feed at /feed/feed.xml
  • Sitemap at /sitemap.xml
  • Individual pages for each tag
HAP starting to understand the file structure

HAP's Realization:

I was amazed how much came pre-built! The RSS feed just... works. (OK, I don't know what an RSS feed is, but it works.) The sitemap updates automatically when I add posts. The tag pages create themselves. Prof. Teeters said, "This is why we start from templates—you get years of best practices for free." And when I have time, I'll find out what an RSS feed is 😇.

The File Structure Explained

HAP looking confused at all the project folders

HAP's Initial Confusion:

At first, all those folders with underscores confused me. Why _data and _includes? Prof. Teeters explained that the underscore tells Eleventy "this is a special folder, not content to publish." Using the underscore is common in a lot of frameworks and now you know why.

eleventy-base-blog File Structure:
eleventy-base-blog/
├── _config/
│   └── filters.js          # Custom date formatting (readableDate, htmlDateString)
├── _data/
│   └── metadata.js         # Site title, author, URL — CHANGE THIS FIRST!
├── _includes/
│   ├── layouts/
│   │   ├── base.njk        # The HTML skeleton (header, nav, footer)
│   │   ├── post.njk        # Blog post wrapper (extends base)
│   │   └── home.njk        # Home page wrapper (extends base)
│   └── postslist.njk       # Reusable "list of posts" component
├── content/
│   ├── blog/               # Your blog posts go here!
│   │   ├── firstpost.md    # Sample posts to study then delete
│   │   └── blog.11tydata.js # Sets defaults for all posts in this folder
│   ├── index.njk           # Home page content
│   ├── blog.njk            # Archive page content
│   └── about.md            # About page — customize this!
├── css/
│   └── index.css           # All the styles (298 lines)
├── public/                 # Static files copied as-is
├── eleventy.config.js      # The brain — plugins, filters, settings
└── package.json            # Dependencies and npm scripts

🔑 Key Files to Know

_data/metadata.js — CHANGE THIS FIRST!

This file contains your site's identity. Here's what the original looks like:

Actual code from eleventy-base-blog:
export default {
    title: "Eleventy Base Blog v9",
    url: "https://example.com/",
    language: "en",
    description: "I am writing about my experiences as a naval navel-gazer.",
    author: {
        name: "Your Name Here",
        email: "youremailaddress@example.com",
        url: "https://example.com/about-me/"
    }
}

Change every value here to make the site yours! The title appears in the browser tab, the description shows in search results, and the author info appears in the RSS feed.

content/blog/blog.11tydata.js — Directory Data

This tiny file sets defaults for ALL posts in the blog folder:

Actual code from eleventy-base-blog:
export default {
    tags: [
        "posts"
    ],
    "layout": "layouts/post.njk",
};

Because of this file, I don't need to add tags: posts or layout: layouts/post.njk to every single blog post. The directory data cascade handles it automatically! This is the data cascade in action from Station 3.

Sample Post Front Matter

Here's what a sample post looks like:

From content/blog/firstpost.md:
---
title: This is my first post.
description: This is a post on My Blog about agile frameworks.
date: 2018-05-01
tags: another tag
---
Leverage agile frameworks to provide a robust synopsis...

Notice how simple the front matter is! The layout and tags: posts come from the directory data file. I only add what's unique to this specific post.

What's Pre-Configured: The Plugins

HAP amazed by all the pre-configured plugins

HAP's Mind = Blown:

I opened eleventy.config.js expecting simple settings. Instead I found eight plugins already configured! Each one adds a major feature. Here's what you get without writing any code:

🎨 Syntax Highlighting

@11ty/eleventy-plugin-syntaxhighlight

Prism.js integration for code blocks. Supports dozens of languages. Already styled with the Okaidia theme.

🖼️ Image Optimization

@11ty/eleventy-img

Automatic AVIF and WebP conversion. Responsive srcset generation. Lazy loading built-in.

📡 RSS Feed

@11ty/eleventy-plugin-rss

Atom feed at /feed/feed.xml. Automatically includes your latest posts. Ready for feed readers.

🧭 Navigation

@11ty/eleventy-navigation

Content-driven menu system. Active page highlighting. Ordered by eleventyNavigation.order.

Plus four more: Heading IDs (IdAttributePlugin), HTML Base paths (HtmlBasePlugin), Input Path transforms, and CSS/JS bundling. More to look up when I get a chance.

From eleventy.config.js (plugin imports):
import { IdAttributePlugin, InputPathToUrlTransformPlugin, HtmlBasePlugin } from "@11ty/eleventy";
import { feedPlugin } from "@11ty/eleventy-plugin-rss";
import pluginSyntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";
import pluginNavigation from "@11ty/eleventy-navigation";
import { eleventyImageTransformPlugin } from "@11ty/eleventy-img";

When I realized all this was already set up, I understood why Prof. Teeters insisted on starting from a template. I would have spent WEEKS figuring out image optimization alone. Instead, I get to focus on my content and design!

The Attribution Story

HAP teaching about attribution and open source

HAP's Important Lesson:

Prof. Teeters was clear about one thing: "When you use someone's work, credit them." Here's the attribution I added to my README:

Attribution for your README:
### Attribution

This Eleventy site was originally built from [eleventy-base-blog](https://github.com/11ty/eleventy-base-blog) by Zach Leatherman ([@zachleat](https://github.com/zachleat)): "A starter repository showing how to build a blog with the Eleventy site generator (using the v3.0 release)."

🟠 Why Attribution Matters:

Prof. Teeters explained: "Open source isn't just about free code—it's about community. Zach spent years building Eleventy and this template. When you credit him, you're not just being polite. You're helping other people discover his work. You're showing that the open source ecosystem works because people share generously and acknowledge each other. That is also why you should always check for the LICENSE and COPYRIGHT if they exist and honor what they say."

That really stuck with me. Now I always check for attribution guidelines when I use open source projects.

🎓 eleventy-base-blog Quick Reference

1

_data/metadata.js

Site title, author, URL — Change this FIRST!

2

content/blog/*.md

Your blog posts — Add your own content here

3

content/about.md

About page — Personalize it with your story

4

css/index.css

All styles — Customize colors and fonts (add at the end!)

5

_includes/layouts/

Page templates — Only change after you understand them

6

eleventy.config.js

Plugins & config — When adding new features

Essential npm Commands

Commands you'll use every day:
# Run ONCE after cloning (installs dependencies)
npm install

# Start development server at localhost:8080
npm start

# Build for production (creates _site folder)
npm run build

Remember: If npm start fails with a weird error, you probably forgot to run npm install first. I learned that one the hard way!