|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Personal blog site using GitHub Issues as the content source. Built on the [Gossip](https://github.com/qianxi0410/gossip) architecture. Issues tagged with `published` label are rendered as blog posts. |
| 8 | + |
| 9 | +**Stack**: Next.js 16 (React 19) + TypeScript + Tailwind CSS 4 + Octokit (GitHub API) |
| 10 | + |
| 11 | +## Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +pnpm dev # Development server (localhost:3000) |
| 15 | +pnpm build # Static export to out/ |
| 16 | +pnpm start # Preview production build |
| 17 | +pnpm lint # ESLint check |
| 18 | +pnpm fix # ESLint with auto-fix |
| 19 | +``` |
| 20 | + |
| 21 | +## Environment Variables |
| 22 | + |
| 23 | +Create `.env.local` with: |
| 24 | +- `OWNER` - GitHub username (required) |
| 25 | +- `REPO` - Repository name (required) |
| 26 | +- `ACCESS_TOKEN` - GitHub PAT with repo scope (required) |
| 27 | +- `GOOGLE_ANALYTICS_ID` - GA tracking ID (optional) |
| 28 | +- `DEPLOY_TARGET` - Set to `gh-pages` for GitHub Pages deployment |
| 29 | + |
| 30 | +## Architecture |
| 31 | + |
| 32 | +**Data Flow**: GitHub Issues → Octokit API → `lib/post.ts` → Static pages at build time |
| 33 | + |
| 34 | +**Key Directories**: |
| 35 | +- `pages/` - Next.js pages router with dynamic routes for posts (`[id].tsx`) and tags (`tag/[id].tsx`) |
| 36 | +- `lib/` - Core data fetching logic |
| 37 | + - `cli.ts` - Octokit client initialization |
| 38 | + - `post.ts` - Fetch posts, tags, and paths from GitHub Issues API |
| 39 | +- `components/` - React components (markdown renderer, header, footer, comments, theme toggle) |
| 40 | +- `gossip.d.ts` - Type definitions for Post, User, and custom NextPageWithLayout |
| 41 | + |
| 42 | +**Configuration**: Site settings in `next.config.js` under `env`: |
| 43 | +- `comment` - Enable Utterances comments (`'true'`/`'false'`) |
| 44 | +- `theme` - Theme mode (`'light'`/`'dark'`/`'both'`) |
| 45 | +- `rss` - Generate RSS feed (`'true'`/`'false'`) |
| 46 | +- `back2top` - Show back-to-top button |
| 47 | +- `mail`, `twitter`, `bio` - User info display |
| 48 | + |
| 49 | +**Deployment**: Uses `output: "export"` for static site generation. For GitHub Pages with non-username.github.io repos, `basePath` is auto-configured. |
0 commit comments