docs: update CLAUDE.md and README.md with comprehensive documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 18:24:14 +01:00
parent dcccf29713
commit c2ebee696d
2 changed files with 875 additions and 257 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,38 +1,24 @@
-# CLAUDE.md
+# CLAUDE.md - Indiekit Eleventy Theme

 This file provides guidance to Claude Code when working with the Indiekit Eleventy theme.

 ## Project Overview

-This is an Eleventy theme designed for use with Indiekit, supporting IndieWeb post types (notes, articles, bookmarks, likes, replies, reposts, photos). It's used as a **Git submodule** in the `indiekit-cloudron` deployment repository.
+This is a comprehensive Eleventy theme designed for IndieWeb-powered personal websites using Indiekit. It renders Micropub posts (articles, notes, photos, bookmarks, likes, replies, reposts), integrates with Indiekit endpoint plugins for enhanced functionality (CV, homepage builder, GitHub, Funkwhale, Last.fm, YouTube, RSS, Microsub, etc.), and includes full webmention support.

 **Live Site:** https://rmendes.net
-**Parent Repo:** `/home/rick/code/indiekit-dev/indiekit-cloudron` (Cloudron deployment)
+**Used as Git submodule in:**
+- `/home/rick/code/indiekit-dev/indiekit-cloudron` (Cloudron deployment)
+- `/home/rick/code/indiekit-dev/indiekit-deploy` (Docker Compose deployment)

-## Submodule Relationship
+## CRITICAL: Submodule Workflow

-```
-indiekit-dev/                             # Workspace root
-└── indiekit-cloudron/                    # Cloudron deployment repo
-    └── eleventy-site/                    # THIS REPO as submodule
-        ├── _includes/
-        ├── _data/
-        ├── content -> /app/data/content  # Symlink at runtime
-        └── ...
-```
+**This repo is used as a Git submodule.** After ANY changes:

-## CRITICAL: Submodule Sync Workflow
-
-**After ANY changes to this repo, you MUST also update the parent repo's submodule reference.**
-
-### Step-by-Step Process
-
-1. **Make changes in this repo** (indiekit-eleventy-theme)
-2. **Commit and push** this repo
-3. **Update the submodule** in indiekit-cloudron:
+1. **Edit, commit, and push** this repo (indiekit-eleventy-theme)
+2. **Update submodule pointer** in parent repo(s):

 ```bash
-# After pushing changes to this theme repo:
 cd /home/rick/code/indiekit-dev/indiekit-cloudron
 git submodule update --remote eleventy-site
 git add eleventy-site
@@ -40,124 +26,522 @@ git commit -m "chore: update eleventy-site submodule"
 git push origin main
 ```

-4. **Redeploy Cloudron** to apply changes:
+3. **Redeploy:**

 ```bash
-cloudron build --no-cache
-cloudron update --app rmendes.net
+cd /home/rick/code/indiekit-dev/indiekit-cloudron
+make prepare  # REQUIRED — copies .rmendes files to non-suffixed versions
+cloudron build --no-cache && cloudron update --app rmendes.net --no-backup
 ```

-### Automated Reminder
+**Common mistake:** Editing files in `indiekit-cloudron/eleventy-site/` instead of this repo. Those changes are ephemeral — always edit here.

-If you forget to update the submodule, the changes will NOT appear on the live site. Always complete both steps.
+## CRITICAL: Indiekit Date Handling Convention

-## Commands
+**All dates MUST be stored and passed as ISO 8601 strings.** This is the universal pattern across Indiekit and ALL `@rmdes/*` plugins.

-```bash
-# Install dependencies (for local development)
-npm install
+### The Rule

-# Build site locally
-npm run build
+- **Storage (MongoDB):** Store dates as ISO strings (`new Date().toISOString()`), NEVER as JavaScript `Date` objects
+- **Controllers:** Pass date strings through to templates unchanged — NO conversion helpers, NO `formatDate()` wrappers
+- **Templates:** Use the `| date` Nunjucks filter for display formatting (e.g., `{{ value | date("PPp") }}`)
+- **Template guards:** Always wrap `| date` in `{% if value %}` to protect against null/undefined

-# Development server with hot reload
-npm run dev
+### Why This Matters
+
+The Nunjucks `| date` filter is `@indiekit/util`'s `formatDate()`, which calls `date-fns parseISO(string)`. It ONLY accepts ISO 8601 strings:
+
+- `Date` objects → `dateString.split is not a function` (CRASH)
+- `null` / `undefined` → `Cannot read properties of undefined (reading 'match')` (CRASH)
+- Pre-formatted strings (e.g., "8 Feb 2025") → Invalid Date (WRONG OUTPUT)
+- ISO strings (e.g., `"2025-02-08T14:30:00.000Z"`) → Correctly formatted (WORKS)
+
+### Correct Pattern
+
+```javascript
+// _data file - store/return ISO strings
+export default async function () {
+  const data = await fetch(...);
+  return {
+    lastSync: new Date().toISOString(),  // ← ISO string
+    items: data.map(item => ({
+      published: item.published || null,  // ← already ISO string from API
+    }))
+  };
+}
+```
+
+```nunjucks
+{# Template - use | date filter, guard for null #}
+{% if lastSync %}
+  {{ lastSync | date("PPp") }}
+{% endif %}
 ```

 ## Architecture

-### Post Types & Collections
+### Data Flow: Plugin → JSON → _data → Template

-| Collection | Path | Description |
-|------------|------|-------------|
-| posts | `content/**/*.md` | All content combined |
-| notes | `content/notes/**/*.md` | Short posts |
-| articles | `content/articles/**/*.md` | Long-form articles |
-| bookmarks | `content/bookmarks/**/*.md` | Saved links |
-| photos | `content/photos/**/*.md` | Photo posts |
-| likes | `content/likes/**/*.md` | Liked content |
-| replies | `content/replies/**/*.md` | Reply posts |
-| reposts | `content/reposts/**/*.md` | Reposted content |
-
-### IndieWeb Property Names
-
-**IMPORTANT:** The Indiekit Eleventy preset uses `camelcaseKeys` to convert Microformat properties:
-
-| Microformat | Indiekit Frontmatter | Template Variable |
-|-------------|---------------------|-------------------|
-| `bookmark-of` | `bookmarkOf` | `bookmarkOf` or `bookmark_of` |
-| `like-of` | `likeOf` | `likeOf` or `like_of` |
-| `in-reply-to` | `inReplyTo` | `inReplyTo` or `in_reply_to` |
-| `repost-of` | `repostOf` | `repostOf` or `repost_of` |
-
-All templates support BOTH camelCase (from Indiekit) and underscore names (legacy) for backwards compatibility:
-
-```nunjucks
-{% set bookmarkedUrl = bookmarkOf or bookmark_of %}
-{% if bookmarkedUrl %}
-  <a href="{{ bookmarkedUrl }}">{{ bookmarkedUrl }}</a>
-{% endif %}
+```
+Indiekit Plugin (backend)
+  → writes JSON to content/.indiekit/*.json
+  → _data/*.js reads JSON file
+  → Nunjucks template renders data
 ```

-### Key Templates
+**Example:** CV plugin flow
+
+1. `@rmdes/indiekit-endpoint-cv` writes `content/.indiekit/cv.json`
+2. `_data/cv.js` reads the JSON file and exports the data
+3. `cv.njk` and `_includes/components/sections/cv-*.njk` render the data
+4. Homepage builder can include CV sections via `homepageConfig.sections`
+
+### Key Files by Function
+
+#### Core Configuration

 | File | Purpose |
 |------|---------|
-| `_includes/layouts/post.njk` | Individual post layout, Bridgy syndication |
-| `_includes/components/reply-context.njk` | Displays bookmark/like/reply/repost context |
-| `bookmarks.njk` | Bookmarks collection page |
-| `likes.njk` | Likes collection page |
-| `replies.njk` | Replies collection page |
-| `reposts.njk` | Reposts collection page |
+| `eleventy.config.js` | Eleventy configuration, plugins, filters, collections, post-build hooks |
+| `tailwind.config.js` | Tailwind CSS configuration (colors, typography) |
+| `postcss.config.js` | PostCSS pipeline (Tailwind, autoprefixer) |
+| `package.json` | Dependencies, scripts (`build`, `dev`, `build:css`) |

-### Bridgy Syndication
+#### Data Files (_data/)

-The `post.njk` layout includes syndication content for Bridgy (Bluesky/Mastodon):
+All `_data/*.js` files are ESM modules that export functions returning data objects. Most fetch from Indiekit plugin JSON files or external APIs.
+
+| File | Data Source | Purpose |
+|------|-------------|---------|
+| `site.js` | Environment variables | Site config (name, URL, author, social links) |
+| `cv.js` | `content/.indiekit/cv.json` | CV data from `@rmdes/indiekit-endpoint-cv` |
+| `homepageConfig.js` | `content/.indiekit/homepage.json` | Homepage layout from `@rmdes/indiekit-endpoint-homepage` |
+| `enabledPostTypes.js` | `content/.indiekit/post-types.json` or env | List of enabled post types for navigation |
+| `urlAliases.js` | `content/.indiekit/url-aliases.json` | Legacy URL mappings for webmentions |
+| `blogrollStatus.js` | Indiekit `/blogrollapi/api/status` | Checks if blogroll plugin is available |
+| `podrollStatus.js` | Indiekit `/podroll/api/status` | Checks if podroll plugin is available |
+| `githubActivity.js` | Indiekit `/githubapi/api/*` or GitHub API | GitHub commits, stars, featured repos |
+| `githubRepos.js` | GitHub API | Starred repositories for sidebar |
+| `funkwhaleActivity.js` | Indiekit Funkwhale plugin API | Listening activity |
+| `lastfmActivity.js` | Indiekit Last.fm plugin API | Scrobbles, loved tracks |
+| `newsActivity.js` | Indiekit IndieNews plugin API | Submitted IndieNews posts |
+| `youtubeChannel.js` | YouTube Data API v3 | Channel info, latest videos, live status |
+| `blueskyFeed.js` | Bluesky AT Protocol API | Recent Bluesky posts for sidebar |
+| `mastodonFeed.js` | Mastodon API | Recent Mastodon posts for sidebar |
+
+**Data Source Pattern:**
+
+Most plugin-dependent data files:
+1. Try to fetch from Indiekit plugin API first
+2. Fall back to direct API (if credentials available)
+3. Return `{ source: "indiekit" | "api" | "error", ...data }`
+4. Templates check `source` to conditionally display
+
+#### Layouts (_includes/layouts/)
+
+| File | Used By | Features |
+|------|---------|----------|
+| `base.njk` | All pages | Base HTML shell with header, footer, nav, meta tags |
+| `home.njk` | Homepage | Two-tier fallback: plugin-driven (homepage builder) or default (hero + recent posts) |
+| `post.njk` | Individual posts | h-entry microformat, Bridgy syndication, webmentions, reply context, photo gallery |
+| `page.njk` | Static pages | Simple content wrapper, no post metadata |
+
+#### Components (_includes/components/)
+
+| Component | Purpose |
+|-----------|---------|
+| `homepage-builder.njk` | Renders plugin-configured homepage layout (single/two-column, sections, sidebar) |
+| `homepage-section.njk` | Router for section types (hero, cv-*, custom-html, recent-posts) |
+| `homepage-sidebar.njk` | Renders plugin-configured sidebar widgets |
+| `homepage-footer.njk` | Optional homepage footer with admin link |
+| `sidebar.njk` | Default sidebar (author card, social activity, GitHub, Funkwhale, blogroll, categories) |
+| `blog-sidebar.njk` | Sidebar for blog/post pages (recent posts, categories) |
+| `h-card.njk` | Microformat2 h-card for author identity |
+| `reply-context.njk` | Displays reply-to/like-of/repost-of/bookmark-of context with h-cite |
+| `webmentions.njk` | Renders likes, reposts, replies from webmention.io + send form |
+| `empty-collection.njk` | Fallback message when a post type collection is empty |
+
+#### Sections (_includes/components/sections/)
+
+Homepage builder sections:
+
+| Section | Config Type | Purpose |
+|---------|-------------|---------|
+| `hero.njk` | `hero` | Full-width hero with avatar, name, bio, social links |
+| `recent-posts.njk` | `recent-posts` | Recent posts grid (configurable maxItems, postTypes filter) |
+| `cv-experience.njk` | `cv-experience` | Work experience timeline from CV data |
+| `cv-skills.njk` | `cv-skills` | Skills with proficiency bars from CV data |
+| `cv-education.njk` | `cv-education` | Education history from CV data |
+| `cv-projects.njk` | `cv-projects` | Featured projects from CV data |
+| `cv-interests.njk` | `cv-interests` | Personal interests from CV data |
+| `custom-html.njk` | `custom-html` | Arbitrary HTML content (from admin UI) |
+
+#### Widgets (_includes/components/widgets/)
+
+Sidebar widgets:
+
+| Widget | Data Source | Purpose |
+|--------|-------------|---------|
+| `author-card.njk` | `site.author` | h-card with avatar, bio, social links |
+| `social-activity.njk` | `blueskyFeed`, `mastodonFeed` | Recent posts from Bluesky/Mastodon |
+| `github-repos.njk` | `githubActivity`, `githubRepos` | Featured repos, recent commits |
+| `funkwhale.njk` | `funkwhaleActivity` | Now playing, listening stats |
+| `recent-posts.njk` | `collections.posts` | Recent posts list (for non-blog pages) |
+| `blogroll.njk` | Blogroll API | Recently updated blogs from OPML/Microsub |
+| `categories.njk` | `collections.categories` | Category list with post counts |
+
+#### Top-Level Templates (*.njk)
+
+Page templates in the root directory:
+
+| Template | Permalink | Purpose |
+|----------|-----------|---------|
+| `index.njk` | `/` | Homepage (uses `home.njk` layout) |
+| `about.njk` | `/about/` | About page with full h-card |
+| `cv.njk` | `/cv/` | CV page with all sections |
+| `blog.njk` | `/blog/` | All posts chronologically |
+| `articles.njk` | `/articles/` | Articles collection |
+| `notes.njk` | `/notes/` | Notes collection |
+| `photos.njk` | `/photos/` | Photos collection |
+| `bookmarks.njk` | `/bookmarks/` | Bookmarks collection |
+| `likes.njk` | `/likes/` | Likes collection |
+| `replies.njk` | `/replies/` | Replies collection |
+| `reposts.njk` | `/reposts/` | Reposts collection |
+| `interactions.njk` | `/interactions/` | Combined social interactions |
+| `slashes.njk` | `/slashes/` | Index of all slash pages |
+| `categories.njk` | `/categories/:slug/` | Posts by category (pagination template) |
+| `categories-index.njk` | `/categories/` | All categories index |
+| `github.njk` | `/github/` | GitHub activity page |
+| `funkwhale.njk` | `/funkwhale/` | Funkwhale listening page |
+| `listening.njk` | `/listening/` | Last.fm listening page |
+| `youtube.njk` | `/youtube/` | YouTube channel page |
+| `blogroll.njk` | `/blogroll/` | Blogroll page (client-side data fetch) |
+| `podroll.njk` | `/podroll/` | Podroll (podcast episodes) page |
+| `news.njk` | `/news/` | IndieNews submissions page |
+| `search.njk` | `/search/` | Pagefind search UI |
+| `feed.njk` | `/feed.xml` | RSS 2.0 feed |
+| `feed-json.njk` | `/feed.json` | JSON Feed 1.1 |
+| `404.njk` | `/404.html` | 404 error page |
+| `changelog.njk` | `/changelog/` | Site changelog |
+| `webmention-debug.njk` | `/webmention-debug/` | Debug page for webmentions |
+
+### Eleventy Configuration Highlights
+
+#### Collections
+
+| Collection | Glob Pattern | Purpose |
+|------------|--------------|---------|
+| `posts` | `content/**/*.md` | All content combined |
+| `articles` | `content/articles/**/*.md` | Long-form posts |
+| `notes` | `content/notes/**/*.md` | Short status updates |
+| `photos` | `content/photos/**/*.md` | Photo posts |
+| `bookmarks` | `content/bookmarks/**/*.md` | Saved links |
+| `likes` | `content/likes/**/*.md` | Liked posts |
+| `replies` | Filtered by `inReplyTo` property | Reply posts |
+| `reposts` | Filtered by `repostOf` property | Repost posts |
+| `pages` | `content/*.md` + `content/pages/*.md` | Slash pages (/about, /now, /uses, etc.) |
+| `feed` | `content/**/*.md` (first 20) | Homepage/RSS feed |
+| `categories` | Deduplicated from all posts | Category list |
+
+**Note:** `replies` and `reposts` collections are dynamically filtered by property, not by directory. Supports both camelCase (`inReplyTo`, `repostOf`) and underscore (`in_reply_to`, `repost_of`) naming.
+
+#### Custom Filters
+
+| Filter | Purpose | Usage |
+|--------|---------|-------|
+| `dateDisplay` | Format date as "January 1, 2025" | `{{ date \| dateDisplay }}` |
+| `isoDate` | Convert to ISO 8601 string | `{{ date \| isoDate }}` |
+| `date` | Format date with custom format | `{{ date \| date("MMM d, yyyy") }}` |
+| `truncate` | Truncate string to max length | `{{ text \| truncate(200) }}` |
+| `ogDescription` | Strip HTML, decode entities, truncate | `{{ content \| ogDescription(200) }}` |
+| `extractFirstImage` | Extract first `<img src>` from content | `{{ content \| extractFirstImage }}` |
+| `obfuscateEmail` | Convert email to HTML entities | `{{ email \| obfuscateEmail }}` |
+| `head` | Get first N items from array | `{{ array \| head(5) }}` |
+| `slugify` | Convert string to slug | `{{ name \| slugify }}` |
+| `hash` | MD5 hash of file for cache busting | `{{ '/css/style.css' \| hash }}` |
+| `timestamp` | Current Unix timestamp | `{{ '' \| timestamp }}` |
+| `webmentionsForUrl` | Filter webmentions by URL + aliases | `{{ webmentions \| webmentionsForUrl(page.url, urlAliases) }}` |
+| `webmentionsByType` | Filter by type (likes, reposts, replies) | `{{ mentions \| webmentionsByType('likes') }}` |
+| `jsonEncode` | JSON.stringify for JSON feed | `{{ value \| jsonEncode }}` |
+| `dateToRfc822` | RFC 2822 format for RSS | `{{ date \| dateToRfc822 }}` |
+
+#### Plugins
+
+| Plugin | Purpose |
+|--------|---------|
+| `@11ty/eleventy-plugin-rss` | RSS feed filters (dateToRfc2822, absoluteUrl) |
+| `@11ty/eleventy-plugin-syntaxhighlight` | Syntax highlighting for code blocks |
+| `@11ty/eleventy-img` | Automatic image optimization (webp, lazy loading) |
+| `eleventy-plugin-embed-everything` | Auto-embed YouTube, Vimeo, Mastodon, Bluesky, Spotify |
+| `@chrisburnell/eleventy-cache-webmentions` | Build-time webmention caching |
+| `@quasibit/eleventy-plugin-sitemap` | Sitemap generation |
+| `html-minifier-terser` | HTML minification (production only) |
+| `pagefind` | Search indexing (post-build via eleventy.after hook) |
+
+#### Transforms
+
+| Transform | Purpose |
+|-----------|---------|
+| `youtube-link-to-embed` | Converts YouTube links to embeds |
+| `htmlmin` | Minifies HTML (build mode only, not watch mode) |
+| `eleventyImageTransformPlugin` | Optimizes `<img>` tags |
+
+#### Post-Build Hooks (`eleventy.after`)
+
+1. **Pagefind indexing** — indexes all HTML files for search
+2. **WebSub hub notification** — notifies subscribers of feed updates (/, /feed.xml, /feed.json)
+
+### IndieWeb Features
+
+#### Microformats2
+
+- **h-card** (author identity): Name, photo, bio, location, social links with `rel="me"`
+- **h-entry** (post markup): All post types properly marked up
+- **h-feed** (feed markup): Machine-readable post lists
+- **h-cite** (reply context): Cites external content in replies/likes/reposts
+
+#### Webmentions
+
+- Build-time caching via `@chrisburnell/eleventy-cache-webmentions`
+- Client-side real-time fetching via `/js/webmentions.js`
+- Displays likes, reposts, replies with avatars
+- Send webmention form on every post
+- Legacy URL support via `urlAliases` (for micro.blog and old blog URLs)
+
+#### IndieAuth
+
+- `rel="me"` links in `<head>` for identity verification
+- Bluesky uses `rel="me atproto"` for AT Protocol verification
+- Fediverse creator meta tag for Mastodon verification
+
+#### Micropub Endpoints
+
+Base layout includes `<link>` tags pointing to Indiekit endpoints:
+
+```html
+<link rel="authorization_endpoint" href="{{ site.url }}/auth">
+<link rel="token_endpoint" href="{{ site.url }}/auth/token">
+<link rel="micropub" href="{{ site.url }}/micropub">
+<link rel="microsub" href="{{ site.url }}/microsub">
+```
+
+#### Bridgy Syndication
+
+Posts include hidden Bridgy syndication content in `post.njk`:

 ```nunjucks
-{# Interaction posts include target URL in syndication #}
 <p class="p-summary e-bridgy-mastodon-content e-bridgy-bluesky-content hidden">
+  {# Interaction posts include emoji + target URL #}
  🔖 {{ bookmarkedUrl }} - {{ description }}
 </p>
 ```

+Bridgy reads this content when syndicating to Bluesky/Mastodon. Interaction types (bookmarks, likes, replies, reposts) include emoji prefix and target URL.
+
 ## Code Style

- ESM modules (`"type": "module"` in package.json)
- Nunjucks templates (`.njk`)
- Tailwind CSS for styling
- `markdownTemplateEngine: false` to prevent parsing `{{` in content
+### TypeScript/JavaScript
+
+- **ESM modules:** `"type": "module"` in package.json
+- **Async data files:** `export default async function () { ... }`
+- **Data source pattern:** Return `{ source: "indiekit" | "api" | "error", ...data }`
+- **Date handling:** Always use ISO 8601 strings (`new Date().toISOString()`)
+
+### Nunjucks Templates
+
+- **Property name compatibility:** Support both camelCase and underscore names:
+
+```nunjucks
+{% set bookmarkedUrl = bookmarkOf or bookmark_of %}
+{% set replyTo = inReplyTo or in_reply_to %}
+```
+
+- **Date filter guards:** Always check for null/undefined:
+
+```nunjucks
+{% if published %}
+  {{ published | date("PPp") }}
+{% endif %}
+```
+
+- **Markdown engine disabled:** `markdownTemplateEngine: false` to prevent parsing `{{` in content
+- **Safe filter usage:** Use `| safe` for trusted HTML content only
+- **Microformats classes:** Follow IndieWeb conventions (h-entry, p-name, dt-published, e-content, u-photo, etc.)
+
+### CSS
+
+- **Tailwind CSS** for all styling
+- **Dark mode:** `dark:` variants, controlled by `.dark` class on `<html>`
+- **Custom color palette:** `primary` (blue) and `surface` (neutral)
+- **Typography plugin:** `prose` classes for content rendering
+- **Responsive design:** Mobile-first, breakpoints: `sm:`, `md:`, `lg:`

 ## Common Tasks

 ### Adding a New Post Type

-1. Create collection in `eleventy.config.js`
-2. Create collection page (e.g., `newtype.njk`)
-3. Update `reply-context.njk` if it has a target URL property
-4. Update `post.njk` Bridgy content if needed
-5. **Commit, push, and update submodule in indiekit-cloudron**
+1. **Create collection** in `eleventy.config.js`:

-### Fixing Template Issues
+```javascript
+eleventyConfig.addCollection("checkins", function (collectionApi) {
+  return collectionApi
+    .getFilteredByGlob("content/checkins/**/*.md")
+    .sort((a, b) => b.date - a.date);
+});
+```

-1. Check property names match Indiekit output (camelCase)
-2. Support both camelCase and underscore for compatibility
-3. Test locally with `npm run dev`
-4. **Commit, push, and update submodule in indiekit-cloudron**
+2. **Create collection page** (e.g., `checkins.njk`):

-## Workspace Context
+```nunjucks
+---
+layout: layouts/page.njk
+title: Check-ins
+withBlogSidebar: true
+permalink: /checkins/
+---
+{% for post in collections.checkins %}
+  {# render post #}
+{% endfor %}
+```

-This repo is part of the Indiekit development workspace at `/home/rick/code/indiekit-dev/`. See the workspace CLAUDE.md for the full repository map.
+3. **Add to enabledPostTypes** (optional, for nav):

-## Related Repositories (all under `/home/rick/code/indiekit-dev/`)
+Edit `_data/enabledPostTypes.js` or set `POST_TYPES` env var.

- **indiekit-cloudron/** - Cloudron deployment, contains this as submodule at `eleventy-site/`
- **indiekit/** - Upstream Indiekit fork (Lerna monorepo)
+4. **Update `reply-context.njk`** if the post type has a target URL property.
+
+5. **Update `post.njk` Bridgy content** if the post type needs special syndication text.
+
+6. **Commit, push, and update submodule.**
+
+### Adding a New Data Source
+
+1. **Create `_data/newSource.js`:**
+
+```javascript
+import EleventyFetch from "@11ty/eleventy-fetch";
+
+const INDIEKIT_URL = process.env.SITE_URL || "https://example.com";
+
+export default async function () {
+  try {
+    const url = `${INDIEKIT_URL}/newapi/api/data`;
+    const data = await EleventyFetch(url, {
+      duration: "15m",
+      type: "json",
+    });
+    return {
+      source: "indiekit",
+      ...data,
+    };
+  } catch (error) {
+    console.log(`[newSource] API unavailable: ${error.message}`);
+    return {
+      source: "error",
+      items: [],
+    };
+  }
+}
+```
+
+2. **Use in template:**
+
+```nunjucks
+{% if newSource and newSource.source == "indiekit" %}
+  {% for item in newSource.items %}
+    {# render item #}
+  {% endfor %}
+{% endif %}
+```
+
+3. **Add status check** to base.njk navigation (if needed).
+
+### Adding a New Homepage Section
+
+1. **Create section template** in `_includes/components/sections/`:
+
+```nunjucks
+{# new-section.njk #}
+{% set sectionConfig = section.config or {} %}
+{% set maxItems = sectionConfig.maxItems or 5 %}
+
+<section class="mb-8 sm:mb-12">
+  <h2 class="text-xl sm:text-2xl font-bold">{{ sectionConfig.title or "New Section" }}</h2>
+  {# render content #}
+</section>
+```
+
+2. **Register in `homepage-section.njk`:**
+
+```nunjucks
+{% if section.type == "new-section" %}
+  {% include "components/sections/new-section.njk" %}
+```
+
+3. **Plugin integration:** The plugin that provides this section should register it via `homepageSections` in Indiekit.
+
+### Debugging Webmentions
+
+1. **Check build-time cache:** Look at `webmention-debug.njk` page
+2. **Check client-side fetch:** Open browser console, check for fetch requests to `/webmentions/api/mentions`
+3. **Verify target URL:** Webmentions must match exact URL (with or without trailing slash)
+4. **Check legacy URLs:** Verify `urlAliases` data includes old URLs if needed
+
+### Theming and Customization
+
+1. **Colors:** Edit `tailwind.config.js` → `theme.extend.colors`
+2. **Typography:** Edit `tailwind.config.js` → `theme.extend.typography`
+3. **CSS utilities:** Add custom utilities to `css/tailwind.css`
+4. **Rebuild CSS:** `npm run build:css` (or `make build:css` in parent repo)

 ## Anti-Patterns

-1. ❌ Forgetting to update submodule in indiekit-cloudron after changes
-2. ❌ Using only underscore property names (Indiekit uses camelCase)
-3. ❌ Using `markdownTemplateEngine: "njk"` (breaks code samples)
-4. ❌ CommonJS syntax in ESM project
-5. ❌ Hardcoding URLs instead of using site data
+1. ❌ **Forgetting to update submodule** after changes
+2. ❌ **Editing files in submodule directory** (`indiekit-cloudron/eleventy-site/`)
+3. ❌ **Using Date objects instead of ISO strings** for dates
+4. ❌ **Not guarding `| date` filters** against null/undefined
+5. ❌ **Using only underscore property names** (support both camelCase and underscore)
+6. ❌ **Using `markdownTemplateEngine: "njk"`** (breaks code samples with `{{`)
+7. ❌ **Hardcoding personal data in templates** (use environment variables)
+8. ❌ **Forgetting to run `make prepare`** before `cloudron build` (deploys stale config)
+9. ❌ **Using unsafe HTML string assignment in client-side JS** (security hooks reject it — use `createElement` + `textContent`)
+10. ❌ **Removing overrides without checking if they shadow submodule files** (causes stale data)
+
+## Troubleshooting
+
+### "dateString.split is not a function"
+
+**Cause:** A Date object was passed to the `| date` filter.
+**Fix:** Store dates as ISO strings from the start: `new Date().toISOString()`
+
+### Stale data in homepage/CV despite correct JSON files
+
+**Cause:** Override file in `indiekit-cloudron/overrides/eleventy-site/` shadows the submodule.
+**Fix:** Delete the override file and reset submodule: `cd eleventy-site && git checkout -- _data/file.js`
+
+### Webmentions not appearing
+
+**Causes:**
+- Build-time cache expired (rebuild to refresh)
+- Client-side JS blocked by CSP (check console)
+- Target URL mismatch (check with/without trailing slash)
+- webmention.io down (check status)
+
+**Fix:** Check `webmention-debug.njk` page, verify `webmentionsForUrl` filter is working.
+
+### Plugin data not appearing in navigation
+
+**Cause:** The plugin's status endpoint is unavailable or returning `source: "error"`.
+**Fix:** Check the plugin's API is running, verify environment variables are set.
+
+### YouTube embeds not working
+
+**Causes:**
+- URL doesn't match pattern (must be youtube.com/watch or youtu.be)
+- Link text doesn't contain "youtube" or URL (transform matches specific patterns)
+
+**Fix:** Use embed plugin shortcode or raw `<iframe>` instead.
+
+## Workspace Context
+
+This repo is part of the Indiekit development workspace at `/home/rick/code/indiekit-dev/`. See the workspace CLAUDE.md for the full repository map and plugin architecture.
--- a/README.md
+++ b/README.md
@@ -2,107 +2,85 @@

 A modern, IndieWeb-native Eleventy theme designed for [Indiekit](https://getindiekit.com/)-powered personal websites. Own your content, syndicate everywhere.

-## IndieWeb Features
+## Features
+
+### IndieWeb First

 This theme is built from the ground up for the IndieWeb:

-### Microformats2 Support
- **h-card**: Complete author profile with photo, name, bio, location, social links
- **h-entry**: All post types properly marked up for parsing
- **h-feed**: Machine-readable feeds for readers and services
- **rel="me"**: Identity verification links for IndieAuth
+- **Microformats2** markup (h-card, h-entry, h-feed, h-cite)
+- **Webmentions** via webmention.io (likes, reposts, replies)
+- **IndieAuth** with rel="me" verification
+- **Micropub** integration with Indiekit
+- **POSSE** syndication to Bluesky, Mastodon, LinkedIn, IndieNews

-### Post Types
-Full support for IndieWeb post types via Indiekit:
- **Articles**: Long-form blog posts
- **Notes**: Short status updates (like tweets)
- **Photos**: Image posts with galleries
- **Bookmarks**: Save and share links
- **Likes**: Appreciate others' content
- **Replies**: Respond to posts across the web
- **Reposts**: Share others' content
- **RSVPs**: Respond to events
+### Full Post Type Support

-### Webmentions
- Receive and display webmentions via [webmention.io](https://webmention.io)
- Reply contexts for responses to external posts
- Grouped display: likes, reposts, and replies
+All IndieWeb post types via Indiekit:
+- **Articles** — Long-form blog posts with titles
+- **Notes** — Short status updates (like tweets)
+- **Photos** — Image posts with multi-photo galleries
+- **Bookmarks** — Save and share links with descriptions
+- **Likes** — Appreciate others' content
+- **Replies** — Respond to posts across the web
+- **Reposts** — Share others' content
+- **Pages** — Root-level slash pages (/about, /now, /uses)

-### Syndication
-Works with Indiekit's syndication plugins:
- Post to Bluesky and Mastodon from your site
- POSSE (Publish Own Site, Syndicate Elsewhere)
+### Homepage Builder

-## Integration Plugins
+Dynamic, plugin-configured homepage with:
+- **Hero section** with avatar, bio, social links
+- **Recent posts** with configurable filtering
+- **CV sections** (experience, skills, education, projects, interests)
+- **Custom HTML** sections from admin UI
+- **Two-column layout** with configurable sidebar
+- **Single-column** or **full-width hero** layouts

-This theme integrates with custom Indiekit endpoint plugins:
+### Plugin Integration

-### [@rmdes/indiekit-endpoint-github](https://github.com/rmdes/indiekit-endpoint-github)
-Display your GitHub activity:
- Recent commits across repositories
- Starred repositories
- Featured project showcase
+Integrates with custom Indiekit endpoint plugins:

-**Configuration:**
-```bash
-GITHUB_USERNAME="your-username"
-GITHUB_TOKEN="ghp_xxxx"
-GITHUB_FEATURED_REPOS="user/repo1,user/repo2"
-```
+| Plugin | Features |
+|--------|----------|
+| `@rmdes/indiekit-endpoint-homepage` | Dynamic homepage builder with admin UI |
+| `@rmdes/indiekit-endpoint-cv` | CV/resume builder with admin UI |
+| `@rmdes/indiekit-endpoint-github` | GitHub activity, commits, stars, featured repos |
+| `@rmdes/indiekit-endpoint-funkwhale` | Listening activity from Funkwhale |
+| `@rmdes/indiekit-endpoint-lastfm` | Scrobbles and loved tracks from Last.fm |
+| `@rmdes/indiekit-endpoint-youtube` | Channel info, latest videos, live status |
+| `@rmdes/indiekit-endpoint-blogroll` | OPML/Microsub blog aggregator with admin UI |
+| `@rmdes/indiekit-endpoint-podroll` | Podcast episode aggregator |
+| `@rmdes/indiekit-endpoint-rss` | RSS feed reader with MongoDB caching |
+| `@rmdes/indiekit-endpoint-microsub` | Social reader with channels and timeline |

-### [@rmdes/indiekit-endpoint-funkwhale](https://github.com/rmdes/indiekit-endpoint-funkwhale)
-Share your listening activity from Funkwhale:
- Now playing / recently played
- Listening statistics
- Top artists and albums
- Favorite tracks
+### Modern Tech Stack

-**Configuration:**
-```bash
-FUNKWHALE_INSTANCE="https://your-instance.com"
-FUNKWHALE_USERNAME="your-username"
-FUNKWHALE_TOKEN="your-api-token"
-```
-
-### [@rmdes/indiekit-endpoint-youtube](https://github.com/rmdes/indiekit-endpoint-youtube)
-Display your YouTube channel(s):
- Channel info with subscriber counts
- Latest videos grid
- Live stream status (live/upcoming/offline)
- Multi-channel support
-
-**Configuration:**
-```bash
-YOUTUBE_API_KEY="your-api-key"
-YOUTUBE_CHANNELS="@channel1,@channel2"
-```
-
-## Social Feeds
-
-The sidebar displays your social activity:
-
-### Bluesky
-```bash
-BLUESKY_HANDLE="you.bsky.social"
-```
-
-### Mastodon
-```bash
-MASTODON_INSTANCE="https://mastodon.social"
-MASTODON_USER="your-username"
-```
+- **Eleventy 3.0** — Fast, flexible static site generator
+- **Tailwind CSS** — Utility-first styling with dark mode
+- **Alpine.js** — Lightweight JavaScript framework
+- **Pagefind** — Fast client-side search
+- **Markdown-it** — Rich markdown with auto-linking
+- **Image optimization** — Automatic WebP conversion, lazy loading

 ## Installation

 ### As a Git Submodule (Recommended)

+This theme is designed to be used as a Git submodule in your Indiekit deployment repository:
+
 ```bash
 # In your Indiekit deployment repo
 git submodule add https://github.com/rmdes/indiekit-eleventy-theme.git eleventy-site
-git submodule update --init
+git submodule update --init --recursive
+cd eleventy-site
+npm install
 ```

-### Standalone
+**Why submodule?** Keeps the theme neutral (no personal data), allows upstream updates, and separates theme development from deployment.
+
+### Standalone Installation
+
+For local development or testing:

 ```bash
 git clone https://github.com/rmdes/indiekit-eleventy-theme.git
@@ -112,7 +90,7 @@ npm install

 ## Configuration

-All configuration is done via environment variables, making the theme fully portable.
+**All configuration is done via environment variables** — the theme contains no hardcoded personal data.

 ### Required Variables

@@ -121,14 +99,12 @@ All configuration is done via environment variables, making the theme fully port
 SITE_URL="https://your-site.com"
 SITE_NAME="Your Site Name"
 SITE_DESCRIPTION="A short description of your site"
+SITE_LOCALE="en"

 # Author info (displayed in h-card)
 AUTHOR_NAME="Your Name"
 AUTHOR_BIO="A short bio about yourself"
 AUTHOR_AVATAR="/images/avatar.jpg"
-AUTHOR_TITLE="Your Title"           # Optional
-AUTHOR_LOCATION="City, Country"     # Optional
-AUTHOR_EMAIL="you@example.com"      # Optional
 ```

 ### Social Links
@@ -139,82 +115,142 @@ Format: `Name|URL|icon,Name|URL|icon`
 SITE_SOCIAL="GitHub|https://github.com/you|github,Mastodon|https://mastodon.social/@you|mastodon,Bluesky|https://bsky.app/profile/you|bluesky"
 ```

-### Full Configuration Reference
+**Auto-generation:** If `SITE_SOCIAL` is not set, social links are automatically generated from feed credentials (GitHub, Bluesky, Mastodon, LinkedIn).

-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SITE_URL` | Your site's full URL | `https://example.com` |
-| `SITE_NAME` | Site title | `My IndieWeb Blog` |
-| `SITE_DESCRIPTION` | Meta description | `An IndieWeb-powered blog` |
-| `SITE_LOCALE` | Language code | `en` |
-| `AUTHOR_NAME` | Your display name | `Blog Author` |
-| `AUTHOR_BIO` | Short biography | - |
-| `AUTHOR_AVATAR` | Path to avatar image | `/images/default-avatar.svg` |
-| `AUTHOR_TITLE` | Job title or tagline | - |
-| `AUTHOR_LOCATION` | Where you're based | - |
-| `AUTHOR_EMAIL` | Contact email | - |
-| `SITE_SOCIAL` | Social links (see format above) | - |
-| `GITHUB_USERNAME` | GitHub username for activity | - |
-| `GITHUB_TOKEN` | GitHub personal access token | - |
-| `GITHUB_FEATURED_REPOS` | Comma-separated repos | - |
-| `BLUESKY_HANDLE` | Bluesky handle | - |
-| `MASTODON_INSTANCE` | Mastodon instance URL | - |
-| `MASTODON_USER` | Mastodon username | - |
-| `FUNKWHALE_INSTANCE` | Funkwhale instance URL | - |
-| `FUNKWHALE_USERNAME` | Funkwhale username | - |
-| `FUNKWHALE_TOKEN` | Funkwhale API token | - |
-| `YOUTUBE_API_KEY` | YouTube Data API key | - |
-| `YOUTUBE_CHANNELS` | Comma-separated channel handles | - |
+### Optional Author Fields
+
+```bash
+AUTHOR_TITLE="Software Developer"
+AUTHOR_LOCATION="City, Country"
+AUTHOR_LOCALITY="City"
+AUTHOR_REGION="State/Province"
+AUTHOR_COUNTRY="Country"
+AUTHOR_ORG="Company Name"
+AUTHOR_PRONOUN="they/them"
+AUTHOR_CATEGORIES="IndieWeb,Open Source,Photography"  # Comma-separated
+AUTHOR_KEY_URL="https://keybase.io/you/pgp_keys.asc"
+AUTHOR_EMAIL="you@example.com"
+```
+
+### Social Activity Feeds
+
+For sidebar social activity widgets:
+
+```bash
+# Bluesky
+BLUESKY_HANDLE="you.bsky.social"
+
+# Mastodon
+MASTODON_INSTANCE="https://mastodon.social"
+MASTODON_USER="your-username"
+```
+
+### Plugin API Credentials
+
+#### GitHub Activity
+```bash
+GITHUB_USERNAME="your-username"
+GITHUB_TOKEN="ghp_xxxx"  # Personal access token (optional, increases rate limit)
+GITHUB_FEATURED_REPOS="user/repo1,user/repo2"  # Comma-separated
+```
+
+#### Funkwhale
+```bash
+FUNKWHALE_INSTANCE="https://your-instance.com"
+FUNKWHALE_USERNAME="your-username"
+FUNKWHALE_TOKEN="your-api-token"
+```
+
+#### YouTube
+```bash
+YOUTUBE_API_KEY="your-api-key"
+YOUTUBE_CHANNELS="@channel1,@channel2"  # Comma-separated handles
+```
+
+#### LinkedIn
+```bash
+LINKEDIN_USERNAME="your-username"
+```
+
+### Post Type Configuration
+
+Control which post types appear in navigation:
+
+```bash
+# Option 1: Environment variable (comma-separated)
+POST_TYPES="article,note,photo,bookmark"
+
+# Option 2: JSON file (written by Indiekit or deployer)
+# Create content/.indiekit/post-types.json:
+# ["article", "note", "photo"]
+```
+
+**Default:** All standard post types enabled (article, note, photo, bookmark, like, reply, repost).

 ## Directory Structure

 ```
-├── _data/              # Data files (fetch from APIs, site config)
-│   ├── site.js         # Site configuration from env vars
-│   ├── blueskyFeed.js  # Bluesky posts fetcher
-│   ├── mastodonFeed.js # Mastodon posts fetcher
-│   ├── githubActivity.js
-│   ├── funkwhaleActivity.js
-│   └── youtubeChannel.js
+indiekit-eleventy-theme/
+├── _data/                    # Data files
+│   ├── site.js              # Site config from env vars
+│   ├── cv.js                # CV data from plugin
+│   ├── homepageConfig.js    # Homepage layout from plugin
+│   ├── enabledPostTypes.js  # Post types for navigation
+│   ├── githubActivity.js    # GitHub data (Indiekit API → GitHub API fallback)
+│   ├── funkwhaleActivity.js # Funkwhale listening activity
+│   ├── lastfmActivity.js    # Last.fm scrobbles
+│   ├── youtubeChannel.js    # YouTube channel info
+│   ├── blueskyFeed.js       # Bluesky posts for sidebar
+│   ├── mastodonFeed.js      # Mastodon posts for sidebar
+│   ├── blogrollStatus.js    # Blogroll API availability check
+│   └── urlAliases.js        # Legacy URL mappings for webmentions
 ├── _includes/
-│   ├── layouts/        # Page layouts (base, home, post)
-│   └── components/     # Reusable components (sidebar, h-card, etc.)
+│   ├── layouts/
+│   │   ├── base.njk         # Base HTML shell (header, footer, nav)
+│   │   ├── home.njk         # Homepage layout (plugin vs default)
+│   │   ├── post.njk         # Individual post (h-entry, webmentions)
+│   │   └── page.njk         # Simple page layout
+│   ├── components/
+│   │   ├── homepage-builder.njk  # Renders plugin homepage config
+│   │   ├── homepage-section.njk  # Section router
+│   │   ├── sidebar.njk           # Default sidebar
+│   │   ├── h-card.njk            # Author identity card
+│   │   ├── reply-context.njk     # Reply/like/repost context
+│   │   └── webmentions.njk       # Webmention display + form
+│   │   ├── sections/
+│   │   │   ├── hero.njk          # Homepage hero
+│   │   │   ├── recent-posts.njk  # Recent posts grid
+│   │   │   ├── cv-experience.njk # Work experience timeline
+│   │   │   ├── cv-skills.njk     # Skills with proficiency
+│   │   │   ├── cv-education.njk  # Education history
+│   │   │   ├── cv-projects.njk   # Featured projects
+│   │   │   ├── cv-interests.njk  # Personal interests
+│   │   │   └── custom-html.njk   # Custom HTML content
+│   │   └── widgets/
+│   │       ├── author-card.njk   # Sidebar h-card
+│   │       ├── social-activity.njk  # Bluesky/Mastodon feed
+│   │       ├── github-repos.njk  # GitHub featured repos
+│   │       ├── funkwhale.njk     # Now playing widget
+│   │       ├── blogroll.njk      # Recently updated blogs
+│   │       └── categories.njk    # Category list
 ├── css/
-│   └── tailwind.css    # Tailwind CSS source
-├── images/             # Static images
-├── *.njk               # Page templates
-├── eleventy.config.js  # Eleventy configuration
-└── package.json
+│   ├── tailwind.css         # Tailwind source
+│   ├── style.css            # Compiled output (generated)
+│   └── prism-theme.css      # Syntax highlighting theme
+├── js/
+│   ├── webmentions.js       # Client-side webmention fetcher
+│   └── admin.js             # Admin auth detection (shows FAB + dashboard link)
+├── images/                  # Static images
+├── *.njk                    # Page templates (blog, about, cv, etc.)
+├── eleventy.config.js       # Eleventy configuration
+├── tailwind.config.js       # Tailwind configuration
+├── postcss.config.js        # PostCSS pipeline
+└── package.json             # Dependencies and scripts
 ```

-## Customization
+## Usage

-### Personal Overrides
-
-When using as a submodule, place override files in your parent repo's `overrides/` directory:
-
-```
-your-repo/
-├── overrides/
-│   └── eleventy-site/
-│       ├── _data/
-│       │   └── cv.js       # Your CV data
-│       └── images/
-│           └── avatar.jpg  # Your photo
-└── eleventy-site/          # This theme (submodule)
-```
-
-Override files are copied over the submodule during build.
-
-### Styling
-
-The theme uses Tailwind CSS. To customize:
-
-1. Edit `tailwind.config.js` for colors, fonts, spacing
-2. Edit `css/tailwind.css` for custom utilities
-3. Run `npm run build:css` to regenerate
-
-## Development
+### Development

 ```bash
 # Install dependencies
@@ -222,20 +258,145 @@ npm install

 # Development server with hot reload
 npm run dev
+# → http://localhost:8080

 # Build for production
 npm run build
+# → Output to _site/

-# Build CSS only
+# Build CSS only (after Tailwind config changes)
 npm run build:css
 ```

+### Content Directory
+
+The theme expects content in a `content/` directory (typically a symlink to Indiekit's content store):
+
+```
+content/
+├── .indiekit/               # Plugin data files
+│   ├── homepage.json        # Homepage builder config
+│   ├── cv.json              # CV data
+│   └── post-types.json      # Enabled post types
+├── articles/
+│   └── 2025-01-15-post.md
+├── notes/
+│   └── 2025-01-15-note.md
+├── photos/
+│   └── 2025-01-15-photo.md
+└── pages/
+    └── about.md             # Slash page
+```
+
+## Customization
+
+### Colors and Typography
+
+Edit `tailwind.config.js`:
+
+```javascript
+theme: {
+  extend: {
+    colors: {
+      primary: {
+        500: "#3b82f6",  // Your primary color
+        600: "#2563eb",
+        // ...
+      },
+    },
+    fontFamily: {
+      sans: ["Your Font", "system-ui", "sans-serif"],
+    },
+  },
+}
+```
+
+Then rebuild CSS: `npm run build:css`
+
+### Dark Mode
+
+The theme includes full dark mode support with `dark:` variants. Toggle is available in header/mobile nav, syncs with system preference.
+
+### Override Files
+
+When using as a submodule, place override files in your parent repo:
+
+```
+your-deployment-repo/
+├── overrides/
+│   └── eleventy-site/
+│       ├── _data/           # Override data files
+│       ├── images/          # Your images
+│       └── about.njk        # Override templates
+└── eleventy-site/           # This theme (submodule)
+```
+
+Override files are copied over the submodule during build.
+
+**Warning:** Be careful with `_data/` overrides — they can shadow dynamic plugin data. Use only for truly static customizations.
+
+## Plugin Integration
+
+### How Plugins Provide Data
+
+Indiekit plugins write JSON files to `content/.indiekit/*.json`. The theme's `_data/*.js` files read these JSON files at build time.
+
+**Example flow:**
+
+1. User edits CV in Indiekit admin UI (`/cv`)
+2. `@rmdes/indiekit-endpoint-cv` saves to `content/.indiekit/cv.json`
+3. Eleventy rebuild triggers (`_data/cv.js` reads the JSON file)
+4. CV sections render with new data
+
+### Homepage Builder
+
+The homepage builder is controlled by `@rmdes/indiekit-endpoint-homepage`:
+
+1. Plugin provides admin UI at `/homepage`
+2. User configures layout, sections, sidebar widgets
+3. Plugin writes `content/.indiekit/homepage.json`
+4. Theme renders configured layout (or falls back to default)
+
+**Fallback:** If no homepage plugin is installed, the theme shows a default layout (hero + recent posts + sidebar).
+
+### Adding Custom Sections
+
+To add a custom homepage section:
+
+1. Create template in `_includes/components/sections/your-section.njk`
+2. Register in `_includes/components/homepage-section.njk`:
+
+```nunjucks
+{% if section.type == "your-section" %}
+  {% include "components/sections/your-section.njk" %}
+{% endif %}
+```
+
+3. Plugin should register the section via `homepageSections` in Indiekit
+
+## Deployment
+
+### Cloudron
+
+See `indiekit-cloudron` repository for Cloudron deployment with this theme as submodule.
+
+### Docker Compose
+
+See `indiekit-deploy` repository for Docker Compose deployment with this theme as submodule.
+
+### Static Host (Netlify, Vercel, etc.)
+
+1. **Not recommended** — Indiekit needs a server for Micropub/Webmentions
+2. For static-only use (no Indiekit), set all env vars and run `npm run build`
+3. Deploy `_site/` directory
+
 ## Pages Included

 | Page | URL | Description |
 |------|-----|-------------|
-| Home | `/` | Recent posts with sidebar |
-| About | `/about/` | Author h-card and bio |
+| Home | `/` | Dynamic homepage (plugin or default) |
+| About | `/about/` | Full h-card with bio |
+| CV | `/cv/` | Resume with all sections |
 | Blog | `/blog/` | All posts chronologically |
 | Articles | `/articles/` | Long-form articles |
 | Notes | `/notes/` | Short status updates |
@@ -244,13 +405,77 @@ npm run build:css
 | Likes | `/likes/` | Liked posts |
 | Replies | `/replies/` | Responses to others |
 | Reposts | `/reposts/` | Shared content |
-| Interactions | `/interactions/` | Combined social activity |
-| GitHub | `/github/` | GitHub activity |
-| Funkwhale | `/funkwhale/` | Listening history |
-| YouTube | `/youtube/` | YouTube channel(s) |
+| Interactions | `/interactions/` | Combined social interactions |
+| Slashes | `/slashes/` | Index of all slash pages |
 | Categories | `/categories/` | Posts by category |
+| GitHub | `/github/` | GitHub activity (if plugin enabled) |
+| Funkwhale | `/funkwhale/` | Listening history (if plugin enabled) |
+| Last.fm | `/listening/` | Last.fm scrobbles (if plugin enabled) |
+| YouTube | `/youtube/` | YouTube channel (if plugin enabled) |
+| Blogroll | `/blogroll/` | Blog aggregator (if plugin enabled) |
+| Podroll | `/podroll/` | Podcast episodes (if plugin enabled) |
+| IndieNews | `/news/` | IndieNews submissions (if plugin enabled) |
+| Search | `/search/` | Pagefind search UI |
 | RSS Feed | `/feed.xml` | RSS 2.0 feed |
 | JSON Feed | `/feed.json` | JSON Feed 1.1 |
+| Changelog | `/changelog/` | Site changelog |
+
+## IndieWeb Resources
+
+- [IndieWebify.me](https://indiewebify.me/) — Test your IndieWeb implementation
+- [Microformats Wiki](https://microformats.org/wiki/h-card) — Microformats2 reference
+- [webmention.io](https://webmention.io/) — Webmention service
+- [IndieAuth](https://indieauth.com/) — Authentication protocol
+- [Bridgy](https://brid.gy/) — Backfeed social interactions
+
+## Troubleshooting
+
+### Webmentions not appearing
+
+**Solution:**
+1. Check `SITE_URL` matches your live domain exactly
+2. Verify webmention.io API is responding: `https://webmention.io/api/mentions?target=https://your-site.com/`
+3. Check build-time cache at `/webmention-debug/`
+4. Ensure post URLs match exactly (with/without trailing slash)
+
+### Plugin data not showing
+
+**Solution:**
+1. Verify the plugin is installed and running in Indiekit
+2. Check environment variables are set correctly
+3. Check `content/.indiekit/*.json` files exist and are valid JSON
+4. Rebuild Eleventy to refresh data: `npm run build`
+
+### Dark mode not working
+
+**Solution:**
+1. Check browser console for JavaScript errors
+2. Verify Alpine.js loaded: `<script src="...alpinejs..."></script>`
+3. Clear localStorage: `localStorage.removeItem('theme')`
+
+### Search not working
+
+**Solution:**
+1. Check Pagefind indexed: `_site/_pagefind/` directory exists
+2. Rebuild with search indexing: `npm run build`
+3. Check search page is not blocked by CSP headers
+
+## Contributing
+
+This theme is tailored for a specific Indiekit deployment but designed to be adaptable. Contributions welcome:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test with `npm run dev`
+5. Submit a pull request
+
+**Guidelines:**
+- Keep theme neutral (no hardcoded personal data)
+- Use environment variables for all configuration
+- Maintain microformats2 markup
+- Test dark mode
+- Follow existing code style (ESM, Nunjucks, Tailwind)

 ## License

@@ -259,6 +484,15 @@ MIT
 ## Credits

 - Built for [Indiekit](https://getindiekit.com/) by Paul Robert Lloyd
+- Inspired by the [IndieWeb](https://indieweb.org/) community
 - Styled with [Tailwind CSS](https://tailwindcss.com/)
 - Icons from [Heroicons](https://heroicons.com/)
- Part of the [IndieWeb](https://indieweb.org/) community
+- Search by [Pagefind](https://pagefind.app/)
+- Static site generation by [Eleventy](https://11ty.dev/)
+
+## Related Projects
+
+- [Indiekit](https://github.com/getindiekit/indiekit) — Micropub server
+- [indiekit-cloudron](https://github.com/rmdes/indiekit-cloudron) — Cloudron deployment
+- [indiekit-deploy](https://github.com/rmdes/indiekit-deploy) — Docker Compose deployment
+- [@rmdes/indiekit-endpoint-*](https://github.com/rmdes?tab=repositories) — Custom Indiekit plugins