# complite

> A complete Eleventy blogging solution. SEO / GEO / AI ready.

complite is a batteries-included Eleventy 3 template for fast, minimal blogs. Zero client-side JavaScript by default, full dark mode, PHP-powered search, contact form with bot protection, and a sane content model so you can focus on the writing.

---

## Welcome to complite

Date: May 20, 2026
Author: Your Name
Tags: post, eleventy, getting-started

You're looking at the first post of a new site built with complite — a complete Eleventy blogging solution for people who write in Markdown and ship static HTML.

This post is a quick tour of what's included and how to get started.

## What you get

Out of the box, complite ships with:

- **Eleventy 3** with ESM configuration and Liquid templates
- **Five layouts**: home, blog archive, article, author profile, and a generic page
- **Dark mode** that works without JavaScript, using a three-layer CSS priority system
- **RSS feed** with an XSL stylesheet for human-readable browser rendering
- **JSON-LD** structured data for search engines
- **Full-text search** powered by SQLite and PHP with fuzzy matching
- **Syntax highlighting** via Prism, loaded only on pages that need it
- **Contact form** backed by a PHP handler with honeypot spam protection

## Project structure

The source lives in `src/`. Data files in `src/_data/` control the site's identity. Layouts and partials live in `src/_includes/`. Blog posts go in `src/blog/posts/`.

```text
src/
├── _data/          # site.json, users.json, person.json
├── _includes/
│   ├── layouts/    # base, home, article, blog, author, contact, page
│   └── partials/   # nav, footer, post-card, pagination, ...
├── blog/posts/     # your markdown posts
├── static/         # CSS, favicons, images
└── index.liquid    # homepage
```

## Writing your first post

Create a new `.md` file in `src/blog/posts/` with front matter like this:

```yaml
---
title: "My First Post"
description: "A short description for search engines and social cards."
date: 2026-05-21
author: admin
tags:
  - writing
---
```

Then write your content in Markdown. Eleventy handles the rest — layout, navigation, RSS, sitemap, and social cards are all automatic.

## Configuration

Edit three files to make complite yours:

1. **`src/_data/site.json`** — site title, URL, description, email
2. **`src/_data/users.json`** — author profiles (name, bio, social links)
3. **`src/_data/person.json`** — JSON-LD identity for search engines

## Running locally

```bash
npm install
npm run dev
```

The dev server starts at `http://localhost:8080` with live reload. For production builds:

```bash
npm run build
```

This minifies HTML, inlines CSS/JS, and outputs everything to `_site/`.

---

That's the tour. Delete this post when you're ready, or keep it as a reference. Happy writing.


---

## Why Static Site Generators Still Matter

Date: May 15, 2026
Author: Your Name
Tags: post, ssg, essay

Every few years someone declares static site generators dead. And every few years, the sites that load fastest, break least, and survive the longest turn out to be static HTML.

Here's why that keeps being true.

## Speed is a feature

A static site is a collection of pre-built HTML files served directly by a web server. There's no database query, no server-side rendering, no cold start. The time between request and first byte is the time it takes to read a file from disk.

This matters more than most developers think. Every 100ms of load time costs engagement. A static site served from a CDN routinely delivers sub-100ms response times worldwide.

## Security by absence

The most secure code is no code. A static site has no server-side runtime, no database, no admin panel, no login form. The entire attack surface is a web server serving files.

There are no SQL injection vulnerabilities because there is no SQL. There are no authentication bypasses because there is no authentication. There are no plugin vulnerabilities because there are no plugins running on the server.

## Version control is your CMS

Every piece of content is a file in a Git repository. This gives you:

- **History**: every change is tracked, attributable, and reversible
- **Branching**: draft posts live on branches, merged when ready
- **Collaboration**: pull requests for content review
- **Backup**: the repository *is* the backup

No database dumps. No export tools. No migration scripts. `git clone` gives you the entire site.

## The build step is a feature, not a tax

Critics call the build step a disadvantage. It's actually where the magic happens:

- Markdown is compiled to semantic HTML
- Templates generate consistent layouts
- Images are optimized and resized
- CSS and JavaScript are minified
- Sitemaps, RSS feeds, and social cards are created automatically

All of this happens once at build time, not on every request. The result is a set of files that can be served by any web server, cached aggressively, and deployed anywhere.

## When not to use a static site

Static sites are wrong for:

- Applications that require real-time user interaction (chat, dashboards)
- Content that changes per-user (personalization, authentication)
- Sites where non-technical editors need a visual CMS

For blogs, documentation, portfolios, landing pages, and any content that changes less often than it's read — static is the right default.

---

The web started static. The best parts of it still are.


---

## Dark Mode Done Right: A CSS-First Approach

Date: May 10, 2026
Author: Your Name
Tags: post, css, design, tutorial

Most dark mode implementations fall into one of two camps: CSS-only (respects system preference but offers no toggle) or JavaScript-only (requires JS to work at all). This starter uses a three-layer approach that combines the best of both.

## The three layers

### Layer 1: System preference (lowest priority)

The base layer uses the `prefers-color-scheme` media query. This works without any JavaScript:

```css
@media (prefers-color-scheme: dark) {
  :root {
    --bg: oklch(15% 0.008 250);
    --fg: oklch(95% 0.005 250);
    /* ... all dark mode variables */
  }
}
```

If your operating system is set to dark mode, the site follows automatically. No JavaScript required.

### Layer 2: JavaScript data attribute (overrides system)

When a user explicitly chooses a theme via the toggle, JavaScript sets a `data-theme` attribute on `<html>` and saves the choice to `localStorage`:

```css
:root[data-theme="dark"] {
  --bg: oklch(15% 0.008 250);
  /* ... dark variables */
}

:root[data-theme="light"] {
  --bg: oklch(99% 0.002 250);
  /* ... light variables */
}
```

This overrides the system preference because attribute selectors have higher specificity than media queries in the cascade.

### Layer 3: CSS `:has()` radio check (highest priority)

The theme toggle is implemented as a pair of radio buttons. When a radio button is checked, CSS `:has()` applies the theme immediately — no JavaScript needed for the visual change:

```css
:root:has(#mode_dark:checked) {
  --bg: oklch(15% 0.008 250);
  /* ... dark variables */
}

:root:has(#mode_light:checked) {
  --bg: oklch(99% 0.002 250);
  /* ... light variables */
}
```

The `:has()` selector has the highest specificity, so it overrides both the system preference and the JavaScript attribute.

## Why radio buttons instead of a button?

Traditional theme toggles use a `<button>` that requires JavaScript to function. Our radio button approach has a key advantage: **it works without JavaScript**.

The radio inputs are visually hidden and their labels are styled as icon buttons. When a user clicks the label, the radio gets `:checked` and CSS applies the theme change via `:has()`. This happens entirely in CSS.

JavaScript only adds one thing: `localStorage` persistence across page loads. Without JS, the toggle still works on the current page — it just resets on navigation.

## Preventing flash of wrong theme

A tiny inline script in `<head>` runs before the page renders:

```js
(function() {
  try {
    var s = localStorage.getItem('complite:theme');
    if (s === 'dark' || s === 'light') {
      document.documentElement.setAttribute('data-theme', s);
    }
  } catch(_) {}
})();
```

This sets the `data-theme` attribute before any CSS is parsed, preventing a flash of the wrong theme on page load.

## The color system

All colors use `oklch()`, a perceptually uniform color space. Dark mode isn't just "invert the colors" — each variable is hand-tuned for readability:

- Background lightness drops from 99% to 15%
- Foreground lightness rises from 15% to 95%
- Accent colors shift to higher lightness for visibility on dark backgrounds
- Border and muted colors are adjusted to maintain contrast ratios

---

The result is a dark mode that works in three scenarios: system preference only (no JS), explicit toggle (with or without JS), and full JavaScript support for persistence. Each layer builds on the last without breaking the ones below it.


---

## SEO for Static Sites: Beyond the Basics

Date: May 5, 2026
Author: Your Name
Tags: post, seo, tutorial

Static sites have a natural SEO advantage: fast load times, clean HTML, and no JavaScript-dependent rendering. But there's more you can do. This starter includes several SEO features that go beyond the basics.

## Structured data with JSON-LD

Every page includes structured data using JSON-LD (JavaScript Object Notation for Linked Data). This helps search engines understand the content without guessing:

**Homepage**: `WebSite`, `WebPage`, `Person`, and `BreadcrumbList` schemas tell search engines about the site, its author, and navigation structure.

**Blog posts**: `BlogPosting` with `datePublished`, `dateModified`, `author`, `headline`, and `image` properties. This powers rich snippets in search results — the date, author name, and thumbnail that appear below a result.

**Author pages**: `Person` and `ProfilePage` schemas link the author's social profiles and establish identity.

All structured data is generated from the same data files you edit (`site.json`, `users.json`, `person.json`), so it stays in sync automatically.

## Open Graph and Twitter Cards

Every page emits Open Graph meta tags for social sharing:

```html
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="..." />
<meta property="og:type" content="article" />
```

Blog posts also include `article:published_time`, `article:modified_time`, and `article:author`. Twitter Card tags ensure large image previews when shared on X.

## Sitemaps that reflect reality

The sitemap is generated dynamically from all pages. What makes it useful:

- Pages with `eleventyExcludeFromCollections` or `unlisted: true` are excluded
- `lastmod` uses the *computed* modified date — the newer of the Git history date and the global `site.modified` setting
- Dates are in ISO 8601 format as required by the spec

## RSS that's human-readable

The RSS feed includes an XSL stylesheet that renders it as a readable page in browsers. When someone visits `/feed.xml` directly, they see a styled page explaining what RSS is and how to subscribe — not raw XML.

## llms.txt for AI agents

The starter includes `llms.txt`, a proposed standard for helping AI language models discover and read site content. It provides:

- A site description
- Links to all blog posts as Markdown files
- Links to all pages
- A full-text version of the entire site

This is the equivalent of `robots.txt` for AI — a structured way to say "here's my content, and here's how to read it."

## Content negotiation

On Apache servers, the `.htaccess` file enables content negotiation. When a client sends `Accept: text/markdown`, blog posts are served as raw Markdown instead of HTML. This is useful for:

- AI agents that prefer Markdown over HTML
- Tools that want to fetch the source content
- RSS readers that process Markdown natively

---

SEO for static sites isn't about tricks. It's about giving machines the same clear structure you give humans — and doing it at build time so it's always correct.


---

## Markdown and the Open Web

Date: April 28, 2026
Author: Your Name
Tags: post, open-web, markdown

There's a quiet idea gaining traction: your content should be available in more than one format. Not just HTML for browsers, but Markdown for machines, RSS for readers, and plain text for everything else.

This starter is built around that idea.

## One source, many formats

Every blog post is written in Markdown. At build time, Eleventy renders it as HTML. But the source Markdown doesn't disappear — it's served alongside the HTML through several mechanisms:

**Direct Markdown files**: Each blog post is available as a `.md` file at a predictable URL. `/blog/my-post/` gives you HTML; `/blog/my-post.md` gives you Markdown.

**Content negotiation**: On Apache, requesting a blog post with `Accept: text/markdown` in the HTTP header returns the Markdown source instead of HTML. Same URL, different representation.

**llms.txt**: A machine-readable index at `/llms.txt` lists all content with Markdown links, following the proposed standard for AI agent discovery.

## Why this matters

### For readers

RSS gives readers a way out of the algorithm. A subscription that delivers content on their terms, in their reader, without tracking or recommendations. The RSS feed in this starter includes an XSL stylesheet so it's human-readable in a browser — because the first step to more RSS usage is making it less intimidating.

### For AI agents

Language models increasingly crawl the web. Markdown is dramatically easier for them to parse than HTML. By offering content as Markdown, you're giving AI agents a clean signal of your content without the noise of navigation, sidebars, and footer boilerplate.

The `llms.txt` file serves as a directory. Instead of crawling your entire site, an AI agent can read one file and understand what's available and how to access it.

### For the open web

Every additional format you serve is a vote for interoperability. It says: I don't control how you consume this content. I just make it available, in standard formats, at stable URLs.

## The Markdown alternate link

Each HTML page includes a `<link rel="alternate">` header pointing to its Markdown equivalent:

```html
<link rel="alternate" type="text/markdown" href="/blog/my-post.md" />
```

This is the same pattern used for RSS (`application/rss+xml`) and translations (`hreflang`). It's a standard mechanism — we're just applying it to a new media type.

## Full-text dumps

The starter also generates a full-text file at `/llms-full.txt` that contains every piece of content on the site in a single document. This is useful for AI training, archival, and anyone who wants to read the entire site offline.

---

The web is better when content is portable. Markdown is the format that makes portability practical — it's readable by humans, parseable by machines, and convertible to anything else. By serving it alongside HTML, we're not replacing the web. We're completing it.


---


## About

This project started as a private template. A few rewrites later, it's still small — about 1,200 lines of code and configuration — but it has earned its opinions. The defaults are the result of running a working blog on top of it, not a wishlist.

## What's in the box

Sensible defaults for the things every blog needs and most starters skimp on:

- Markdown with front matter, syntax-highlighted code blocks, and clean typography.
- RSS feed — generated from a single template, no plugins required.
- A full light/dark mode that reads correctly at 11pm and at 11am.
- An author model that supports multi-author blogs without inventing a CMS.
- Full-text search powered by SQLite and PHP — no external services needed.
- A 404 page worth reading and a sitemap that's actually valid.

## What it isn't

Not a CMS. Not a framework. Not a place to learn React. If you want one of those, this repository would be the wrong starting point and you'd be doing yourself a favour by picking a different one.

## Who it's for

Writers who already think in Markdown. Designers who want to ship a portfolio in an afternoon. Engineers who like reading the HTML their site emits. People who want their grandmother to be able to read their blog on a 2014 phone.

## How to start

Clone the repository, run `npm install` and `npm start`, then open your first post in `src/blog/posts/`. Everything else is documented in the [README](https://github.com/jcubic/complite).

---

Built and maintained with care. Code is MIT-licensed.


---

## Privacy Policy

This site is a static HTML website. It does not use cookies, analytics scripts, tracking pixels, or third-party advertising. Your visit is not logged by default.

## Contact form

When you use the [contact form](/contact/), the information you submit (name, email, subject, message) is sent via email to the site owner. This data is used only to reply to you and is not stored in any database, shared with third parties, or used for marketing.

## Subscribe form

The subscribe form in the footer is a placeholder. If the site owner connects it to a newsletter service, that service's privacy policy will apply. By default, no data is collected.

## Hosting

This site may be hosted on a server that collects standard HTTP access logs (IP address, user agent, timestamp, requested URL). These logs are used for server maintenance and security, not for tracking individual visitors.

## External resources

This site loads fonts from Google Fonts. Google's [privacy policy](https://policies.google.com/privacy) applies to those requests.

## Your rights

If you've submitted data through the contact form and want it deleted, [get in touch](/contact/) and it will be handled promptly.

---

Last updated: May 2026.