cici 0.4.2 → 0.4.3

package/README.md

@@ -1,101 +1,111 @@
 # cici
 
-A beautifully simple blog and memo app that just works.
+A beautifully simple, git-backed blog & memo app. Write Markdown, keep everything in
+your own Git repo, serve it anywhere. Inspired by [tinymind](https://github.com/mazzzystar/tinymind);
+live at [blog.minghe.me](https://blog.minghe.me).
 
-Write thoughts. Share ideas. Let GitHub handle the rest. Originally inspired by [tinymind](https://github.com/mazzzystar/tinymind), now see it in action at [blog.minghe.me](https://blog.minghe.me).
+**cici is pure tooling.** Your content — posts, memos, config — lives in *your* repo or
+folder. You install cici (`npm i cici` / `npx cici`) and point it at that content. This
+repo ships only the app plus a tiny `sample-content/` demo used for local dev and tests.
 
-> **cici is pure tooling.** Your blog *content* — posts, memos, site config — lives in
-> a **separate content repo** (or a local folder), not here. This repo ships only the
-> app plus a small `sample-content/` demo fixture used for `next dev` and tests.
+## Content layout
 
+Your content lives under a **`data/`** folder — in a Git repo this sits at the repo root,
+and it's exactly what a deploy serves:
 
-## What You Get
+```
+data/
+  blog/            # one <slug>.md per post (front-matter + Markdown)
+  memos.json       # short-form memos
+  site-config.json # title, author, social links (optional)
+  highlights/      # one <slug>.json per post (optional)
+  likes.json       # like counts (optional)
+  assets/          # images uploaded from the editor (local mode)
+```
 
-- **Rich Blog Posts** - Markdown, syntax highlighting, math, images
-- **Quick Memos** - Instant thoughts with location tagging  
-- **Discussion Integration** - Auto-connect HN, Reddit, V2EX comments
-- **GitHub Powered** - Your data, your control, always
-- **Works Everywhere** - Mobile-first, lightning fast
+## Use it locally
 
-## Get Started in 2 Minutes
+Run cici against a local folder or a GitHub repo — no clone, no build:
 
 ```bash
-git clone https://github.com/metrue/cici.git
-cd cici && npm install && npm run dev
-```
+# Serve AND edit local content (open /editor to write; changes save to disk).
+# --dir points at the folder that contains blog/ — in a content repo that's data/:
+npx cici --dir ./data
 
-**That's it.** Visit `localhost:3000` — `next dev` serves the shipped `sample-content/`
-demo fixture. Point cici at your own content repo/folder (below) to write for real.
+# Serve a GitHub content repo (reads its data/ automatically, read-only)
+npx cici --repo owner/name
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/metrue/cici)
+# ...with a token, edit it too (commits back to the repo)
+npx cici --repo owner/name --token ghp_xxx --port 4000
+```
 
-## Run it anywhere with `npx` (no deploy)
+Options: `--port, -p` (default 3000), `--host` (default 127.0.0.1). Run `npx cici --help`.
 
-cici has a runtime layer with two backends — **local files** and a **GitHub repo** —
-behind one content contract. Point the CLI at either:
+## Deploy on Vercel
 
-```bash
-# Local folder — serve AND edit, straight from disk (no GitHub, no sign-in)
-npx cici --dir ~/my-blog
+Your **content repo** is the thing you deploy — it just depends on cici. No app source,
+no fork of this repo.
 
-# Any GitHub content repo — read-only viewer
-npx cici --repo metrue/cici
+**1.** In your content repo, add `package.json`:
 
-# ...with a token, edit that repo too
-npx cici --repo owner/name --token ghp_xxx --port 4000
+```json
+{
+  "private": true,
+  "scripts": { "build": "cici build" },
+  "dependencies": { "cici": "^0.4.3" }
+}
 ```
 
-Two more commands for deploying cici *with* a content repo on a host (e.g. Vercel):
-
-```bash
-# From inside a content repo: stage cici's prebuilt Next output into ./ for the host
-npx cici build
+**2.** Add `vercel.json` (so Vercel serves cici's output instead of running its own Next build):
 
-# Boot the server from preset env (CICI_REPO/CICI_TOKEN/CICI_DIR/PORT/HOST) —
-# no --dir/--repo needed; the host supplies the backend via env
-npx cici start
+```json
+{ "framework": null, "buildCommand": "cici build" }
 ```
 
-The content contract (same for `--dir` and `--repo`):
+`cici build` emits Vercel's Build Output API (`.vercel/output/`) — cici's prebuilt server
+as one function plus static assets. Vercel serves it directly.
 
-```
-<root>/
-  blog/            # one <slug>.md per post (front-matter + markdown)
-  memos.json       # your memos
-  site-config.json # optional site settings
-  likes.json       # optional
-  highlights/      # optional, one <slug>.json per post
-  assets/          # images uploaded from the editor land here (local mode)
-```
+**3.** Set environment variables on the Vercel project:
 
-When editing is available (local mode, or a GitHub repo with a token) open `/editor`
-to write posts and memos — everything is written back through the provider: to disk
-in `--dir` mode, or committed to the repo in `--repo --token` mode.
+| Var | Value |
+|-----|-------|
+| `CICI_REPO` | `owner/name` of your content repo |
+| `GITHUB_ID` / `GITHUB_SECRET` | a [GitHub OAuth app](https://github.com/settings/developers) (callback `<site>/api/auth/callback/github`) — `/editor` sign-in |
+| `NEXTAUTH_SECRET` | any random string (signs the session) |
+| `NEXTAUTH_URL` | your site URL, e.g. `https://blog.example.com` |
+| `CICI_TOKEN` | **Optional — private repos only.** GitHub token with **Contents: read & write**. A public content repo needs no token: cici reads it anonymously, and `/editor` commits with your GitHub sign-in. |
 
-### Architecture
+If your content repo is **public**, that's the recommended setup — no server token to
+manage, and only you (the repo owner, via sign-in) can publish. Reads work for everyone,
+writes only for whoever can push to the repo.
 
-- **Runtime layer** (`lib/runtime/`): a `ContentProvider` interface with `LocalProvider`
-  and `GitHubProvider` implementations; `getProvider()` is the single factory that picks
-  one from `CICI_DIR` / `CICI_REPO` / `GITHUB_USERNAME`.
-- **Render layer** (`app/`, `components/`): depends only on `getProvider()` — never on
-  `fs` or Octokit directly.
+Deploy. cici reads your content from `CICI_REPO` at request time, so edits (via `/editor`
+or a `git push`) show up without a redeploy.
 
-## Documentation
+> Prefer a plain Node host (Railway / Render / Fly / a VPS / Docker)? Skip `cici build`
+> and run `cici start` with the same `CICI_*` env — it boots the server directly.
 
-**[→ Complete cici Guide](/blog/cofe)** - Everything you need in one place:
+## Editing
 
-- Quick start & GitHub OAuth setup
-- Customization & analytics integration  
-- API reference & GraphQL queries
-- Deployment & performance tips
-- Migration from other platforms
-- Troubleshooting & best practices
+Open `/editor` to write posts and memos. In `--dir` mode it writes to disk; with a token
+(`--repo --token`, or `CICI_TOKEN` on a deploy) it commits back to your content repo.
 
+## Develop cici itself
 
-## Screenshots
+```bash
+git clone https://github.com/metrue/cici.git
+cd cici && npm install && npm run dev   # serves the bundled sample-content/
+npm test
+```
 
-![Home Desktop](https://github.com/metrue/cici/blob/main/assets/images/home_desktop.png?raw=true)
+### Architecture
+
+- **Runtime layer** (`lib/runtime/`): a `ContentProvider` interface with `LocalProvider`
+  and `GitHubProvider`; `getProvider()` picks one from `CICI_DIR` / `CICI_REPO` env.
+- **Render layer** (`app/`, `components/`): depends only on `getProvider()` — never on
+  `fs` or Octokit directly.
+- **CLI** (`bin/cici.js`): `--dir` / `--repo` (serve), `build` (Vercel Build Output), `start` (boot from env).
 
-![Memos Desktop](https://github.com/metrue/cici/blob/main/assets/images/memos_desktop.png?raw=true)
+## Documentation
 
-![Memo Editor](https://github.com/metrue/cici/blob/main/assets/images/memo_editor.png?raw=true)
+**[→ The Complete cici Guide](/blog/cofe)** — setup, customization, GraphQL API, deployment, and tips.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cici",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "private": false,
   "description": "cici — a git-backed blog CMS (pure tooling; your posts live in a separate content repo). Run `npx cici --dir <dir>` or `--repo <owner/name>` to serve/edit, or `cici build` / `cici start` to deploy.",
   "repository": {