diff --git a/CLAUDE.md b/CLAUDE.md index 1f85dc4..104fb7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,552 +1,134 @@ -# CLAUDE.md - Indiekit Eleventy Theme +# CLAUDE.md — svemagie/blog -This file provides guidance to Claude Code when working with the Indiekit Eleventy theme. +This is Sven's personal IndieWeb blog at **blog.giersig.eu**. +Stack: Eleventy 3 · Tailwind CSS 3 · Alpine.js · IndieKit (Micropub) · Cloudron hosting. -## Project Overview +The theme lives in a separate repo (`svemagie/blog-eleventy-indiekit`, tracked as the `theme` remote). This repo is the live site and has diverged significantly from that upstream — treat them as related but independent. -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 -**Used as Git submodule in:** -- `/home/rick/code/indiekit-dev/indiekit-cloudron` (Cloudron deployment) -- `/home/rick/code/indiekit-dev/indiekit-deploy` (Docker Compose deployment) - -## CRITICAL: Submodule Workflow - -**This repo is used as a Git submodule.** After ANY changes: - -1. **Edit, commit, and push** this repo (indiekit-eleventy-theme) -2. **Update submodule pointer** in parent repo(s): - -```bash -cd /home/rick/code/indiekit-dev/indiekit-cloudron -git submodule update --remote eleventy-site -git add eleventy-site -git commit -m "chore: update eleventy-site submodule" -git push origin main -``` - -3. **Redeploy:** - -```bash -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 -``` - -**Common mistake:** Editing files in `indiekit-cloudron/eleventy-site/` instead of this repo. Those changes are ephemeral — always edit here. - -## CRITICAL: Indiekit Date Handling Convention - -**All dates MUST be stored and passed as ISO 8601 strings.** This is the universal pattern across Indiekit and ALL `@rmdes/*` plugins. - -### The Rule - -- **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 - -### 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 -### Data Flow: Plugin → JSON → _data → Template +### Core files +- `eleventy.config.js` — monolithic config: all plugins, filters, shortcodes, collections, passthrough copies +- `_data/site.js` — all site config driven by env vars; no hardcoded personal values in source +- `_data/*.js` — individual data files for feeds (GitHub, Bluesky, Mastodon, Last.fm, etc.) +- `_includes/layouts/` — page layout templates (`base.njk`, `post.njk`, etc.) +- `_includes/components/` — reusable Nunjucks partials +- `lib/` — build-time JS utilities (`og.js`, `unfurl-shortcode.js`, `data-fetch.js`) +- `scripts/` — maintenance scripts (`check-upstream-widget-drift.mjs`) -``` -Indiekit Plugin (backend, jail node) - → writes JSON to content/.indiekit/*.json - → GitHub Action fetches homepage.json via SSH before build - → _data/*.js reads JSON file - → Nunjucks template renders data -``` +### Content +`content/` is a **symlink** to IndieKit's managed content directory — it is gitignored but Eleventy processes it via `setUseGitIgnore(false)`. Never edit posts in `content/` directly; they are created and updated via IndieKit's Micropub endpoint. -**homepage.json is fetched at deploy time** — the `deploy.yml` workflow SSHes into the server and runs `sudo bastille cmd node cat /usr/local/indiekit/content/.indiekit/homepage.json` before the Eleventy build. This ensures the build always uses the latest admin-saved config. Do not rely on the committed `content/.indiekit/homepage.json` as source of truth; it may be stale. +Post types: `articles`, `notes`, `bookmarks`, `likes`, `replies`, `reposts`, `photos`, `pages`. -**Example:** CV plugin flow +### Build output +`_site/` — generated site, not committed. Also excluded from Eleventy processing to prevent loops. -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 | -|------|---------| -| `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`) | - -#### Data Files (_data/) - -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` (fetched from node jail at deploy time) | 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 | Always delegates to `homepage-builder.njk` (requires `content/.indiekit/homepage.json`) | -| `post.njk` | Individual posts | h-entry microformat, Bridgy syndication, webmentions, reply context, photo gallery; includes `post-interactions.njk` → `comments.njk` → `webmentions.njk` in that order | -| `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` | Full-width footer below the main layout; renders `homepageConfig.footer` sections in a 3-column grid | -| `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 | -| `post-interactions.njk` | Per-post inbound webmentions (likes, reposts, replies, mentions) in card style; client-side AlpineJS, fetches from `/webmentions/api/mentions` + `/conversations/api/mentions`, hidden when empty; placed before comments | -| `webmentions.njk` | Build-time webmention display (facepile + reply cards) + send form; shown after comments | -| `comments.njk` | IndieAuth-gated comment form and thread; shown between post-interactions and webmentions | -| `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; carries the homepage **h-card** microformat | -| `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 `` 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 `` 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"`. On the homepage, the h-card lives in `_includes/components/sections/hero.njk` (`h-card` on `
`, `p-name`/`u-url`/`u-photo`/`p-job-title`/`p-note` on inner elements). The `authorUrl` resolves from `homepageConfig.identity.url` → `site.author.url` → `site.url`. -- **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 `` for identity verification -- Bluesky uses `rel="me atproto"` for AT Protocol verification -- Fediverse creator meta tag for Mastodon verification - -#### Micropub Endpoints - -Base layout includes `` tags pointing to Indiekit endpoints: - -```html - - - - -``` - -#### Bridgy Syndication - -Posts include hidden Bridgy syndication content in `post.njk`: - -```nunjucks - -``` - -Bridgy reads this content when syndicating to Bluesky/Mastodon. Interaction types (bookmarks, likes, replies, reposts) include emoji prefix and target URL. - -## Code Style - -### 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 `` -- **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`: - -```javascript -eleventyConfig.addCollection("checkins", function (collectionApi) { - return collectionApi - .getFilteredByGlob("content/checkins/**/*.md") - .sort((a, b) => b.date - a.date); -}); -``` - -2. **Create collection page** (e.g., `checkins.njk`): - -```nunjucks --- -layout: layouts/page.njk -title: Check-ins -withBlogSidebar: true -permalink: /checkins/ + +## Key custom systems + +### Digital Garden (`gardenStage`) +Posts carry a `gardenStage` front-matter value: `seedling`, `budding`, `cultivating`, or `evergreen`. Stage can also be derived from nested tags (`garden/cultivate` → `cultivating`, etc.). + +**Garden badge component** (`_includes/components/garden-badge.njk`): +- In post-list templates, set `gardenStage` from `post.data.gardenStage` before including, or rely on the component's own fallback. +- The badge is included **once per post-type branch** (`{% if post.type == "article" %}...{% elif %}...{% endif %}`). Do not add it outside those branches — it will render for every post regardless of type and produce duplicate badges. + +### AI Disclosure +Posts declare AI involvement level in front matter (e.g. `aiCode: T1/C2`). Rendered as a badge below post content and as a hidden `.p-ai-code-level` span in list cards. + +### Nested tags +Categories use Obsidian-style path notation (`lang/de`, `tech/programming`). The `nestedSlugify()` function in `eleventy.config.js` preserves `/` separators during slug generation. Slugification is applied per segment. + +### Unfurl shortcode +`{% unfurl url %}` generates a rich link preview card with caching. Cache lives in `.cache/unfurl/`. The shortcode is registered from `lib/unfurl-shortcode.js`. + +### OG image generation +`lib/og.js` + `lib/og-cli.js` — generates Open Graph images at build time using Satori and resvg-js. Avatar is pulled from `AUTHOR_AVATAR` env var. + +### Upstream drift check +```bash +npm run check:upstream-widgets # Report widget drift vs theme remote +npm run check:upstream-widgets:strict # Exit 1 if any drift found +``` + --- -{% for post in collections.checkins %} - {# render post #} -{% endfor %} + +## Templates — things to know + +### `blog.njk` +The main blog listing. Each post type (article, note, bookmark, like, repost, reply, photo) has its own `{% if/elif %}` branch. The AI badge and pagination are **outside** those branches at the `
  • ` / `