11ty-project-base — Eleventy Starter Template

SHA-256: a1315c52de62ee0ab5a3ac4826fd6a11002c47a215c0f2db7396127bf4567acb

2026-10-13T13:49:41.856Z

# 11ty project base

A clean, future‑proof Eleventy v3 starter wired with Tailwind CSS v4, a tasteful prose theme, dark mode, smart minification, first‑class 404/500 pages, optional SPA fallback, and a one‑command dev workflow. Minimal ceremony, maximum mileage.

---

## Features

- **Eleventy v3 (ESM)** with a tidy directory layout  
- **Tailwind v4 (CLI)** with tokens via `@theme`, Typography plugin, and a tiny base prose theme  
- **Dark mode** toggle (no FOUC, respects OS preference)  
- **Minification in production** (`html-minifier-terser`), XML/RSS kept safe  
- **404 & 500 pages** at the site root; SEO‑safe `noindex`  
- **Optional SPA fallback** via `_redirects` (or `vercel.json`)  
- **JS bundling** via esbuild (context API), outputs to `public/assets/js`  
- **Netlify‑ready** (`netlify.toml` with headers + Node version)  
- **One command to rule them all**: `npm run dev:all`

---

## Using this starter for a new project

Spin up a fresh site from this starter in a brand-new directory. Pick the route that suits you:

### Option A — GitHub “Use this template” (UI)
1. Open this repo on GitHub and click **Use this template → Create a new repository**.
2. Name your new repo (e.g. `my-new-site`) and create it.
3. Clone it locally:
   ```bash
   git clone [email protected]:<YOUR-GH-USER>/my-new-site.git
   cd my-new-site
   npm install
   npm run dev:all
   ```

### Option B — GitHub CLI (from template)
Replace `OWNER/REPO` with this starter’s full name.
```bash
gh repo create my-new-site   --template OWNER/REPO   --public   --clone
cd my-new-site
npm install
npm run dev:all
```

### Option C — Shallow clone (no template UI)
```bash
git clone --depth=1 [email protected]:OWNER/REPO.git my-new-site
cd my-new-site
rm -rf .git
git init -b main
git add .
git commit -m "chore: bootstrap from starter"
# (optional) set up the remote:
# git remote add origin [email protected]:<YOUR-GH-USER>/my-new-site.git
# git push -u origin main
npm install
npm run dev:all
```

---

### Post-setup checklist (2 minutes)

- **Project metadata**
  - `package.json`: update `name`, `description`, `repository`, `author`, `homepage`, `bugs`.
  - `README.md`: change the short description to match the new site.
  - `LICENCE`: ensure the copyright holder/year suit this project.

- **Site identity**
  - `_data/site.js`: set your site `name` (and any other fields you add later).
  - `_includes/layouts/base.njk`: update header nav links (and email in 404/500).
  - Replace `public/assets/images/example.jpg` with a real image or remove it.

- **Dev & build**
  - Ensure Node **v20+** (run `nvm use` if you use `nvm`; see `.nvmrc`).
  - Dev: `npm run dev:all` → http://localhost:8080
  - Prod build: `npm run build:all` (outputs to `_site/`)

- **Deploy (Netlify)**
  - Connect the new repo in Netlify.
  - Build command: `npm run build:all`
  - Publish directory: `_site`
  - Node version: 20 (in **Site settings** or via `netlify.toml`).
  - `_redirects` and headers in `netlify.toml` are picked up automatically.

- **CI (GitHub Actions)**
  - The included workflow builds on pushes/PRs to `main`/`master`.
  - Check the **Actions** tab after your first push.

---

### Common tweaks
- Want a different container width? Adjust `.container-page` (and optionally add `.container-narrow`) in `styles/Tailwind.css`.
- Need extra colours or typography? Add tokens under `@theme` and style `.prose` as needed.
- Not using JS yet? Remove the `JS` process from `dev:all` or leave it—it’s harmless.

---

## Directory structure

```
11ty-project-base/
├─ _config/             # Eleventy hooks
│  ├─ filters.js
│  ├─ shortcodes.js
│  └─ transforms.js
├─ _data/               # Global data
│  ├─ env.js
│  └─ site.js
├─ _helpers/
│  └─ build-js.js       # esbuild bundler (context API)
├─ _includes/
│  └─ layouts/
│  |   └─ base.njk
│  └─ partials/
├─ content/             # Eleventy input
│  ├─ 404.njk
│  ├─ 500.njk
│  ├─ index.njk
│  └─ styles/
│     └─ main.css       # generated by Tailwind CLI (gitignored)
├─ public/              # passthrough to site root
│  ├─ _redirects        # optional
│  └─ assets/
│     └─ images/
│        └─ example.jpg
├─ scripts/             # your app JS entry(ies)
│  └─ main.js
├─ styles/
│  └─ Tailwind.css      # Tailwind v4 entry (source)
├─ _site/               # Eleventy output (gitignored)
├─ .gitignore
├─ .nvmrc
├─ eleventy.config.js
├─ netlify.toml
└─ package.json
```

---

## Requirements

- Node **v20+** (see `.nvmrc`)
- npm

---

## Quick start

```bash
npm install
npm run dev:all
# open http://localhost:8080
```

**Production build:**
```bash
npm run build:all
```

---

## NPM scripts

```json
{
  "scripts": {
    "dev": "ELEVENTY_ENV=dev eleventy --serve",
    "build": "ELEVENTY_ENV=prod eleventy",
    "clean": "rimraf _site",

    "tw:init": "tailwindcss -i styles/Tailwind.css -o content/styles/main.css",
    "tw:watch": "tailwindcss -i styles/Tailwind.css -o content/styles/main.css --watch",
    "tw:build": "tailwindcss -i styles/Tailwind.css -o content/styles/main.css --minify",

    "js:watch": "node _helpers/build-js.js --watch",
    "js:build": "node _helpers/build-js.js",

    "predev:all": "npm run tw:init",
    "dev:all": "concurrently -k -n ELEVENTY,TAILWIND,JS -c auto \"npm:dev\" \"npm:tw:watch\" \"npm:js:watch\"",
    "build:all": "npm run tw:build && npm run js:build && npm run build"
  }
}
```

- `dev:all` runs Eleventy + Tailwind watcher + esbuild watcher.  
- `build:all` compiles Tailwind, bundles JS, then builds Eleventy (with minification).

---

## Eleventy configuration

`eleventy.config.js`:
- **Input**: `content/`
- **Includes**: `_includes/`
- **Data**: `_data/`
- **Output**: `_site/`
- **Passthrough**: `public/` → `/`, `content/styles/` → `/assets` (so compiled CSS is served as `/assets/main.css`)
- **Watches**: `content/styles`, `styles`, `scripts`
- **Transforms**: registered from `_config/transforms.js`
- **Template engines**: Nunjucks for html/md/data

---

## Minification and XML safety

`_config/transforms.js` includes two transforms:

1. **`html-minify`** (prod only): uses `html-minifier-terser` for `.html?` files with safe defaults (`collapseWhitespace`, `removeComments`, `minifyJS/CSS`, etc.).  
2. **`xml-preserve`**: for `.xml`, `.rss`, `.atom`, `.xsl`, we **do not minify**; we only **normalise** newlines and trim trailing whitespace to keep feeds/sitemaps parser‑friendly.

Production mode is toggled by `ELEVENTY_ENV=prod` in the `build` script.

---

## Tailwind v4 setup

- Entry CSS: `styles/Tailwind.css`  
- Output CSS: `content/styles/main.css` (gitignored; copied to `/assets/main.css`)  
- Plugins: `@tailwindcss/typography`  
- Tokens: declared via `@theme` (e.g., `--color-vividcrimson`, `--color-huntergreen`)  
- Sources: `@import "tailwindcss" source("../content");` and `@source "../_includes";` to scan Eleventy templates.

### Base prose theme and links

- All links: subtle underline, medium weight, **crimson**; underline removed on hover/focus.  
- `.prose` content: neutral text, **muted hunter‑green** blockquotes (text + left border), sensible code/pre colours.

Apply to Markdown/CMS output by wrapping rendered HTML with `.prose` (e.g., on article containers or template partials).

---

## Dark mode (no FOUC + toggle)

- I set `<html data-theme="dark|light">` early via a tiny inline script in `base.njk` (uses `localStorage` or OS preference).  
- Dark tokens adjust link colour (brighter crimson), quote accents, prose neutrals, and card backgrounds.  
- A **“Toggle theme”** button in the header flips state and saves preference.

You can move the toggle script into `scripts/main.js` later if you prefer bundling.

---

## Header/footer layout

- Header/footer content is wrapped with `.container-page` (or `.container-narrow` if enabled) to align with main content.  
- Optional subtle backgrounds with dark‑mode variants to separate header/footer from main content.

---

## 404 & 500 pages

- `content/404.njk` → `/404.html`  
- `content/500.njk` → `/500.html`  
- Both use `noindex` and are excluded from collections.  
- Eleventy Dev Server routes unknown paths to `/404.html` locally.  
- Netlify/Vercel/Cloudflare Pages/GitHub Pages use `/404.html` automatically for static sites.

---

## Redirects & SPA fallback

- `public/_redirects` is passed through to the site root:  
  - Add custom redirects like `/old /new 301`.  
  - **Optional SPA**: uncomment `/* /index.html 200` to route all paths to the homepage (disables static 404).  
- **Vercel**: use `vercel.json` rewrites if you need SPA behaviour.  
- **GitHub Pages**: no rewrites; use the “404‑as‑SPA loader” trick if you must ship an SPA.

> Do not enable SPA fallback **and** keep a static 404 at the same time. Pick one.

---

## JavaScript bundling

- Entry: `scripts/main.js`  
- Bundler: `_helpers/build-js.js` uses **esbuild context API** for watching:  
  - Output: `public/assets/js/bundle.js` (passthrough to `_site/assets/js`)  
  - Include in layout: `<script src="/assets/js/bundle.js" defer></script>`

---

## Netlify deploy

`netlify.toml`:

```toml
[build]
  command = "npm run build:all"
  publish = "_site"

[build.environment]
  NODE_VERSION = "20"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*"
  [headers.values]
    Referrer-Policy = "strict-origin-when-cross-origin"
    X-Content-Type-Options = "nosniff"
    X-Frame-Options = "DENY"
```

- Netlify will also read `_redirects` from the published root.  
- If you convert to an SPA later, add a 200 rewrite here **or** in `_redirects` (not both).

---

## Global data

- `_data/site.js`: name/year for layout chrome.  
- `_data/env.js`: simple environment surface (`ELEVENTY_ENV`, Node version) for templates/data.

---

## Customising

- Add collections (e.g., `content/posts/`) and define them in `eleventy.config.js`.  
- Extend typography (e.g., `.prose-lg` sections) with component classes.  
- Add more filters/shortcodes in `_config/filters.js` and `_config/shortcodes.js`.  
- Replace the grid tiles on the homepage with your real sections.

---

## Troubleshooting

- **Passthrough collision**:  
  Error: “Multiple passthrough copy files are trying to write to the same output file (`_site/assets/main.css`).”  
  Fix: only passthrough **compiled** CSS (`content/styles` → `/assets`). Do **not** passthrough `styles/`.

- **esbuild “Invalid option 'watch'”**:  
  Use the **context API** (`const ctx = await esbuild.context(opts); await ctx.watch();`) as implemented in `_helpers/build-js.js`.

- **No CSS on first load**:  
  Ensure `predev:all` runs `tw:init` so `content/styles/main.css` exists before Eleventy starts.

- **SPA fallback eats 404**:  
  If you enable `/* /index.html 200`, you will not see your static 404. That’s expected.

- **Dark mode flashes**:  
  Make sure the inline theme bootstrap runs **before** the CSS link in `base.njk`.

---

## Licence

See [`LICENCE`](LICENCE).

---

## Credits

Built with Eleventy and Tailwind. Happy building!