8000 Add Personal minimal writing-first theme by kiran-brahma · Pull Request #6 · kiran-brahma/microfeed · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions themes/personal/.agents/skills/develop-microfeed-theme/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: develop-microfeed-theme
description: Develop, revise, build, validate, test, and preview a microfeed theme repository. Use when editing microfeed-theme.json, declared format v1 or v2 theme files, migrating a theme to v2, public Pages, navigation, search integration, shared shell code, theme build sources, fixtures, schemas, packaged assets, or immutable theme versions.
---

# Develop a microfeed theme

1. Read `THEME.md`, `microfeed-theme.json`, and the schemas under `.microfeed/schemas/` completely before editing.
2. Before changing the public shell, Page layout, navigation, or search, read [references/public-site.md](references/public-site.md) completely. Preserve its platform/theme ownership boundary and stable hooks.
3. Inspect package scripts and source directories. Run `yarn install` before the baseline checks when the repository has a Yarn package. Do not rely on dependencies from a parent workspace.
4. If the repository has build sources, edit those sources and regenerate all declared output files; do not hand-edit generated bundles. If an export contains only rendered files, edit the declared files directly. Keep all files inside the package directory and modify only declared templates, declared assets, build sources, fixtures, and documentation.
5. Run the package build when p 10BC8 resent, then prefer the repository scripts `yarn validate` and `yarn test`. Fall back to `theme-kit validate . --json` and `theme-kit test . --json` only when those scripts are absent. Repair every diagnostic.
6. Prefer `yarn preview` for visual review, falling back to `theme-kit preview .` only when needed. Use supplied fixtures first; use a public JSON feed only when real content is needed. Check Feed, Item, Page, Search, RSS, shared navigation, the search popup, mobile behavior, and the special 404 layout. Stop the preview server after verification.
7. Increment the manifest SemVer before installing changed content. Never reuse a published package ID and version for different content.
8. Install as inactive. Do not activate a theme or change a live site without explicit permission.

## Bundle CSS and JavaScript

- The installer never runs Vite, Webpack, Tailwind, or package scripts. Keep TypeScript, source CSS, bundler configuration, and `node_modules` in the repository; build and commit every generated runtime file before validation or installation.
- For a small bundle that must work without R2, capture Vite or Webpack output and embed CSS in `<style>` inside `web-header.mustache` and JavaScript in `<script>` inside `web-body-end.mustache`. Keep `assets: []`. These generated slots are stored in the immutable D1 theme row, count toward the theme text limits, and can be edited in an Admin-derived draft. Escape any `</script>` sequence when generating inline JavaScript.
- For larger or independently cacheable output, configure Vite with deterministic library-mode filenames, or Webpack with a deterministic `output.filename` and `MiniCssExtractPlugin`. Emit files such as `assets/theme.css` and `assets/theme.js`, declare every file in the manifest, and reference them as `{{_theme.asset_base_url}}theme.css` and `{{_theme.asset_base_url}}theme.js` without repeating `assets/`.
- Declared asset bytes are uploaded to immutable R2 keys during installation; D1 stores their metadata and owning theme version. They require R2 on the target instance and cannot be replaced from a V1 Admin draft. The standalone preview serves the same references from its local asset handler. Never hard-code `/assets/`, `/media/`, an R2 hostname, or an environment name.
- After changing build sources, run the package build and its deterministic/staleness check when present. Confirm generated bundles are declared, exclude source maps and other unsupported development artifacts, validate and test the rendered package, then bump SemVer.

Keep packaged assets declared in the manifest. Themes with assets need R2 enabled on the target instance; text-only and inline-bundle themes do not. Never create screenshots unless the user explicitly asks for them.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Develop microfeed themes"
short_description: "Build and validate microfeed theme packages"
default_prompt: "Use $develop-microfeed-theme to create or update this microfeed theme safely."
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# Public Pages, navigation, and search

Read this reference before changing a theme's public shell, Page template,
navigation, or search experience.

Public Pages and search require format v2. When an exported theme is format v1,
preserve its package ID, increment its immutable version, set
`formatVersion` to `2`, add the `webPage` and `webSearch` manifest paths
and templates, then follow this contract. Keep the six existing slots while
adding those two; validate and preview every view before installation.

## Theme and platform responsibilities

A format v2 theme owns:

- Feed, Item, Page, and Search page structure and presentation.
- Shared markup immediately after `<body>` and before `</body>`.
- The RSS browser stylesheet.
- Visible search triggers, Search page markup, and responsive Page navigation.
- CSS that customizes the platform-provided search interface.

microfeed owns:

- Page visibility, public routing, the editable 404 fallback, and navigation
filtering and ordering.
- The public search endpoint, popup dialog, Command/Ctrl+K behavior, typeahead
debounce and cancellation, safe highlighting, and result rendering.
- Injecting the search dialog and its script after the theme's Body end slot.

Do not copy the search dialog, call `/search.json` yourself, or implement
another typeahead controller in theme JavaScript. Change the main microfeed
application—not a theme—when the requested work changes search behavior,
query semantics, Page visibility, or navigation data.

## Eight theme slots

| Manifest key | Responsibility |
| --- | --- |
| `webFeed` | Feed index and pagination content |
| `webItem` | One Item page |
| `webPage` | One standalone Page, including the special 404 Page |
| `webSearch` | Dedicated `/search/` page |
| `webHeader` | Shared `<head>` metadata, CSS, and optional scripts |
| `webBodyStart` | Shared public shell immediately after `<body>` |
| `webBodyEnd` | Shared footer or scripts immediately before platform additions |
| `rssStylesheet` | Complete XSL stylesheet for browser-rendered RSS |

Put site-wide navigation in Body start when it should appear once on Feed,
Item, Page, and Search. Put a shared footer and compiled progressive
enhancements in Body end. Keep each page template focused on its `<main>`
content. Body start and Body end receive the same common Mustache context as
the page templates.

## Pages and navigation

The Page template receives `page`. Render trusted Page HTML with triple
Mustache and provide a text fallback when useful:

```html
<main>
{{#page}}
<article>
<h1>{{title}}</h1>
<div>{{{content_html}}}</div>
</article>
{{/page}}
</main>
```

The schema documents all Page fields, including dates, metadata, status,
navigation settings, and `is_not_found_page`. The special 404 Page can be
previewed at `/404/` and is also rendered for real missing URLs.

Every public HTML slot receives the ordered `navigation_pages` array. It
contains only Published Pages with **Show in navigation** enabled, in the order
chosen in Admin. Draft and Unlisted Pages and the special 404 Page are
excluded. Navigation is website-only; it does not add Pages to RSS or JSON
Feed.

Render links from the supplied URL and label:

```html
<nav aria-label="Site navigation">
{{#navigation_pages}}
<a href="{{url}}" data-microfeed-nav-item>{{navigation_label}}</a>
{{/navigation_pages}}
</nav>
```

The theme owns mobile behavior and overflow. Test with at least three entries
so an overflow menu is exercised. Do not sort the array again or infer Page
visibility in theme code.

## Search popup

microfeed injects one accessible dialog into every format v2 public HTML page.
Add `data-microfeed-search-open` to each visible control that should open it:

```html
<button
type="button"
aria-haspopup="dialog"
aria-controls="microfeed-search-dialog"
data-microfeed-search-open
>
Search
</button>
```

A desktop search-looking control may be readonly and use the same hook; the
actual typeahead input belongs to the popup. Command+K on macOS and Ctrl+K on
other platforms work without theme JavaScript.

## Dedicated Search page

The Search template receives `search.query`. Live results are rendered safely
into the stable hooks by microfeed. Use a normal GET form so search still has a
clear URL and submission behavior:

```html
<form action="/search/" method="get" role="search" data-microfeed-search-scope>
<label for="site-search">Search this site</label>
<input
id="site-search"
name="q"
type="search"
value="{{search.query}}"
autocomplete="off"
data-microfeed-search-input
>
<button type="submit">Search</button>
<div
aria-live="polite"
data-microfeed-search-results
data-microfeed-search-details
></div>
</form>
```

`data-microfeed-search-details` opts into a short publication date and a
two-line excerpt with safe matched-text highlighting. Omit it only when the
design intentionally needs title-only results.

Standalone and Admin previews use representative item and Page results. They
display a warning because live Ajax search is deliberately disabled in preview.
The Search page template and popup remain fully styleable there.

## Search styling

Define these tokens in the Web header to align the injected popup with the
theme:

```css
:root {
--mf-accent: #0969da;
--mf-background: #ffffff;
--mf-surface: #f6f8fa;
--mf-text: #1f2328;
--mf-muted: #57606a;
--mf-border: #d0d7de;
}
```

Prefer the tokens for broad design changes. For targeted rules, use the stable
`data-microfeed-search-*` hooks and these public classes:

- `.mf-public-search`
- `.mf-public-search__panel`, `__header`, `__close`, `__input-row`, and
`__results`
- `.mf-public-search-result`, `__type`, and `__details`

Keep focus styles, labels, keyboard behavior, mobile layout, and reduced-motion
preferences accessible.

## Preview checklist

Use the bundled fixtures first, then run `yarn preview` and verify:

- Feed, Item, Page, Search, and RSS views.
- Desktop and mobile widths.
- Exactly one shared navigation and footer.
- Zero, one, two, and three-or-more navigation entries.
- Search controls open the popup by click and Command/Ctrl+K.
- Search preview results include both an Item and a Page.
- The Search page form, excerpts, highlighting, empty state, and long text.
- The special 404 Page layout and short-page footer placement.

If build sources exist, edit them and regenerate declared outputs. An exported
repository may contain only the rendered installable files; in that case,
preserve the exact baseline, edit those declared files directly, and increment
the immutable theme version before installation.
2 changes: 2 additions & 0 deletions themes/personal/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
.yarn/
node_modules/
3 changes: 3 additions & 0 deletions themes/personal/.yarnrc.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
nodeLinker: node-modules
npmPreapprovedPackages:
- "@microfeed/theme-kit"
31 changes: 31 additions & 0 deletions themes/personal/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Personal theme

A clean, minimal, writing-first personal website theme for microfeed
(`personal.minimal@0.1.0`).

- Editorial serif typography with a warm paper palette and generous whitespace.
- Writing-first feed: date, title, excerpt, category chips, and series notes.
- Podcast support: audio items render an inline player; video, document,
image, and external-url items keep their native presentation.
- Categories and series render on the feed and item pages.
- A contact form (name / email / message) appears on a Page whose slug is
`contact` and submits to the platform's `/contact/submit/` endpoint.
- Platform navigation, search popup, dedicated Search page, and the special
404 Page follow the public-site contract.

## Develop

Use Node.js 22.12 or newer and Yarn 4:

```console
yarn install
yarn validate
yarn test
yarn preview
```

Read [THEME.md](./THEME.md), `microfeed-theme.json`, and the schemas under
`.microfeed/schemas/` before editing. Before installing changed content,
increment the semantic version in `microfeed-theme.json`. Install the new
version as inactive, preview it, and activate it only as a separate confirmed
action.
58 changes: 58 additions & 0 deletions themes/personal/THEME.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Personal theme

This directory is a complete, versioned microfeed theme package
(`personal.minimal`). Coding agents should edit only the paths declared in
`microfeed-theme.json`, declared assets, and optional fixtures. Do not edit
files under `.microfeed/schemas/`. The bundled `develop-microfeed-theme` skill
gives coding agents the same safe workflow. Its
[public-site reference](./.agents/skills/develop-microfeed-theme/references/public-site.md)
documents Pages, shared navigation, the search popup, the Search page, stable
hooks, styling tokens, and the platform/theme ownership boundary. Read it
before changing public layout or behavior. Never create screenshots unless the
owner explicitly requests them.

## Design

- **Typography**: Georgia serif for body and headings; system sans-serif for
the search control. Comfortable reading measure (42rem) and 1.7 line height.
- **Palette**: warm paper background, warm ink text, terracotta accent, using
the `--mf-*` design tokens so Admin color changes apply.
- **Layout**: single column, generous whitespace, minimal chrome. Navigation
and search live in the header; the footer carries only the copyright line.

## Edit and test loop

1. Read `microfeed-theme.json` and `.microfeed/schemas/theme-context.schema.json`.
2. Edit the eight declared Mustache/XSL files. Mustache is logicless:
variables, sections, inverted sections, and iteration only.
3. Run `yarn validate`.
4. Run `yarn test`.
5. Run `yarn preview` and inspect feed, item, Page, Search, RSS, mobile, and
desktop views.
6. Increment the immutable semantic version before installation.

The render context is the public JSON Feed plus `current_year`,
`_theme.package_id`, `_theme.version`, and `_theme.asset_base_url`. It also
supplies the current `page`, ordered `navigation_pages`, and Search page state
when relevant. Items expose `categories` (array of `{id, name, slug}`) and
`series` (`{id, kind, name, slug, series_number?}`) from the personal-site
features. On item pages, use `items.0`; the old `item` alias is deprecated.

The contact form renders on a Page whose slug is `contact` (the platform sets
`is_contact_page`). It POSTs `name`, `email`, and `message` to
`/contact/submit/`; the platform redirects back with `?sent=1` on success and
`?error=1` on validation failure.

Keep shared navigation in Body start when it should render once across Feed,
Item, Page, and Search. Keep a shared footer and progressive enhancements in
Body end. microfeed injects and controls the public search dialog; themes add
visible `data-microfeed-search-open` triggers, provide the documented Search
page hooks, and style the interface without duplicating its Ajax or keyboard
controller.

Theme code is trusted when activated, so install only repositories you trust.

Declare every packaged asset in the manifest. For files under `assets/`,
reference them as `{{_theme.asset_base_url}}logo.png` (without repeating the
`assets/` directory). The preview server and an installed site resolve that
same URL to the packaged file.
1 change: 1 addition & 0 deletions themes/personal/assets/.gitkeep
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@

67 changes: 67 additions & 0 deletions themes/personal/fixtures/custom.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
{
"version": "https://jsonfeed.org/version/1.1",
"title": "Personal theme fixture",
"description": "Representative content for Feed, Item, Page, navigation, and Search previews.",
"home_page_url": "https://example.test/",
"items": [
{
"id": "essay-fixture",
"title": "An essay with categories and a series",
"content_html": "<p>This essay belongs to a series and carries two categories.</p>",
"content_text": "This essay belongs to a series and carries two categories.",
"date_published": "2026-08-13T10:00:00.000Z",
"categories": [
{"id": "cat-writing", "name": "Writing", "slug": "writing"},
{"id": "cat-notes", "name": "Notes", "slug": "notes"}
],
"series": {
"id": "series-essays",
"kind": "post",
"name": "Field Notes",
"slug": "field-notes",
"series_number": 2
},
"_microfeed": {
"web_url": "https://example.test/i/essay-fixture/"
}
},
{
"id": "podcast-fixture",
"title": "A podcast episode with an audio player",
"content_html": "<p>An audio episode that keeps podcast support.</p>",
"content_text": "An audio episode that keeps podcast support.",
"date_published": "2026-08-12T09:00:00.000Z",
"attachments": [
{
"url": "https://example.test/media/audio.mp3",
"mime_type": "audio/mpeg",
"size_in_bytes": 1000000
}
],
"categories": [
{"id": "cat-podcast", "name": "Podcast", "slug": "podcast"}
],
"series": {
"id": "series-podcast",
"kind": "podcast",
"name": "The Show",
"slug": "the-show",
"series_number": 5
},
"_microfeed": {
"web_url": "https://example.test/i/podcast-fixture/",
"is_audio": true,
"duration_hhmmss": "12:34"
}
},
{
"id": "searchable-fixture",
"title": "Searchable Page and Item styles",
"content_text": "Use this longer description to verify excerpts, wrapping, and matched-text highlighting.",
"date_published": "2026-08-11T08:00:00.000Z",
"_microfeed": {
"web_url": "https://example.test/i/searchable-fixture/"
}
}
]
}
Loading
Loading
0