dckc/captoys
1
0 Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity

potluck, diigo-cache: docs one line per paragraph; potluck deploy caveat

Browse Source 
Obsidian and GitHub render each newline as a line break, so the
hard-wrapped READMEs and CONTRIBUTINGs rendered ragged. Whitespace
only, except a note in potluck's CONTRIBUTING that other workerd
hosts are untested: they'd have to supply the D1 and R2 bindings.

Generated-by: Claude Opus 5.5
This commit is contained in:
dckc committed 2026-10-09 01:30:56 -05:00
1 parent a25bd699e1
commit c66aaea366
4 files changed
+53 -182
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

potluck/CONTRIBUTING.md
+17 -55
View File
@@ -1,44 +1,17 @@
# Contributing to potluck
potluck started as EmDash's `cloudflare:blog` template
(`pnpm create emdash@latest`); it's part of
[the capsite goal tree](../capsite-checklist.md), where it is the site
that publishes the weekly roundup.
potluck started as EmDash's `cloudflare:blog` template (`pnpm create emdash@latest`); it's part of [the capsite goal tree](../capsite-checklist.md), where it is the site that publishes the weekly roundup.
## How it's put together
- **Issues** are the `issues` collection
([seed/issues.json](seed/issues.json)): `title`, `week` (an ISO week,
`2026-W40`), `dek` (one-line summary), `body` (Portable Text). The
slug is the week, lowercased: `/issues/2026-w40`.
[issues-sketch.md](issues-sketch.md) is the dry run behind the three
sample issues: real public bookmarks, editorial lines marked *draft*.
- **Pages:** home and `/issues` list issues
([src/pages/issues/](src/pages/issues/)); `/tag/<tag>` lists issues
by diigo tag; search and `/rss.xml` cover issues. The `posts`
collection and its pages are the template's, still in place.
- **Microformats:** an issue list is an `h-feed` of `h-entry`s; an
issue is an `h-entry` (`p-name`, `dt-published`, `p-summary`,
`e-content`). In issue bodies,
[CiteLink.astro](src/components/CiteLink.astro) marks off-site links
as `h-cite` and `/tag/<tag>` links as rel-tag `p-category`.
- **Look:** plain HTML, after kmjn.org's
[Plain HTML with a few bureaucratic gestures](https://www.kmjn.org/notes/modern_plain_html.html):
system fonts (no webfonts), one ~800px column, links in the text
color with a dotted underline. Restyle in
[src/styles/theme.css](src/styles/theme.css), which overrides the
defaults in `tokens.css` (unlayered, so it always wins); don't edit
`tokens.css` or `Base.astro` for visual changes. Colors use
`light-dark(<light>, <dark>)`.
- **Issues** are the `issues` collection ([seed/issues.json](seed/issues.json)): `title`, `week` (an ISO week, `2026-W40`), `dek` (one-line summary), `body` (Portable Text). The slug is the week, lowercased: `/issues/2026-w40`. [issues-sketch.md](issues-sketch.md) is the dry run behind the three sample issues: real public bookmarks, editorial lines marked *draft*.
- **Pages:** home and `/issues` list issues ([src/pages/issues/](src/pages/issues/)); `/tag/<tag>` lists issues by diigo tag; search and `/rss.xml` cover issues. The `posts` collection and its pages are the template's, still in place.
- **Microformats:** an issue list is an `h-feed` of `h-entry`s; an issue is an `h-entry` (`p-name`, `dt-published`, `p-summary`, `e-content`). In issue bodies, [CiteLink.astro](src/components/CiteLink.astro) marks off-site links as `h-cite` and `/tag/<tag>` links as rel-tag `p-category`.
- **Look:** plain HTML, after kmjn.org's [Plain HTML with a few bureaucratic gestures](https://www.kmjn.org/notes/modern_plain_html.html): system fonts (no webfonts), one ~800px column, links in the text color with a dotted underline. Restyle in [src/styles/theme.css](src/styles/theme.css), which overrides the defaults in `tokens.css` (unlayered, so it always wins); don't edit `tokens.css` or `Base.astro` for visual changes. Colors use `light-dark(<light>, <dark>)`.
## Seeds
[seed/seed.json](seed/seed.json) (site settings, menus, widgets, the
template's collections) is applied on the first request to an empty
database. [seed/issues.json](seed/issues.json) is separate:
`pnpm seed:issues` applies it to the local D1 database, which exists
after the dev server's first request. Run it with the dev server
stopped.
[seed/seed.json](seed/seed.json) (site settings, menus, widgets, the template's collections) is applied on the first request to an empty database. [seed/issues.json](seed/issues.json) is separate: `pnpm seed:issues` applies it to the local D1 database, which exists after the dev server's first request. Run it with the dev server stopped.
## Checks
@@ -49,22 +22,14 @@ pnpm build
## EmDash rules
- All content pages are server-rendered (`output: "server"`); no
`getStaticPaths()` for CMS content.
- Image fields are objects (`{ src, alt }`), not strings; render with
`<Image image={...} />` from `"emdash/ui"`.
- `entry.id` is the slug (for URLs); `entry.data.id` is the database
ULID (for API calls like `getEntryTerms`).
- When Astro's cache is enabled, pass query hints to
`Astro.cache.set(cacheHint)`.
- Taxonomy names in queries match the seed's `"name"` exactly (`"tag"`,
not `"tags"`).
- `npx emdash types` regenerates `emdash-env.d.ts` from a running site
(the dev server also regenerates it on start).
- All content pages are server-rendered (`output: "server"`); no `getStaticPaths()` for CMS content.
- Image fields are objects (`{ src, alt }`), not strings; render with `<Image image={...} />` from `"emdash/ui"`.
- `entry.id` is the slug (for URLs); `entry.data.id` is the database ULID (for API calls like `getEntryTerms`).
- When Astro's cache is enabled, pass query hints to `Astro.cache.set(cacheHint)`.
- Taxonomy names in queries match the seed's `"name"` exactly (`"tag"`, not `"tags"`).
- `npx emdash types` regenerates `emdash-env.d.ts` from a running site (the dev server also regenerates it on start).
The EmDash docs are an MCP server at `https://docs.emdashcms.com/mcp`
(wired up in `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`).
Check them rather than recalling APIs from memory.
The EmDash docs are an MCP server at `https://docs.emdashcms.com/mcp` (wired up in `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). Check them rather than recalling APIs from memory.
## Deploying
@@ -73,13 +38,10 @@ pnpm wrangler login
pnpm deploy
```
The first deploy provisions the D1 database and R2 bucket named in
[wrangler.jsonc](wrangler.jsonc). See
[Deploy to Cloudflare](https://docs.emdashcms.com/deployment/cloudflare/).
The first deploy provisions the D1 database and R2 bucket named in [wrangler.jsonc](wrangler.jsonc). See [Deploy to Cloudflare](https://docs.emdashcms.com/deployment/cloudflare/).
Other workerd hosts are untested: the site uses D1 and R2 through `@emdash-cms/cloudflare` and the Cloudflare adapter (locally, miniflare stands in for both), so a host has to supply those two bindings.
## For agents
`AGENTS.md` is a symlink to this file. capsite's
[working rules](../AGENTS.md) apply here too (the dev server is the
user's to start and stop). EmDash skills are in `.agents/skills/`:
`building-emdash-site` (start here), `creating-plugins`, `emdash-cli`.
`AGENTS.md` is a symlink to this file. capsite's [working rules](../AGENTS.md) apply here too (the dev server is the user's to start and stop). EmDash skills are in `.agents/skills/`: `building-emdash-site` (start here), `creating-plugins`, `emdash-cli`.