```
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/
---
{% for post in collections.checkins %}
{# render post #}
{% endfor %}
```
3. **Add to enabledPostTypes** (optional, for nav):
Edit `_data/enabledPostTypes.js` or set `POST_TYPES` env var.
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 %}
{{ sectionConfig.title or "New Section" }}
{# render content #}
```
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** 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 `