From b9cd442d904402c59d8b9451199897cd75545ea5 Mon Sep 17 00:00:00 2001 From: Thijs van Hoof Date: Thu, 19 Mar 2026 13:21:32 +0100 Subject: [PATCH 1/4] add docs --- CLAUDE.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 9 ++++++ 2 files changed, 82 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..40d058e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,73 @@ +# CLAUDE.md + +Project context for AI agents working in this repository. + +## What this repo is + +Documentation site for [GLIF](https://www.glif.io), a DeFi protocol on Filecoin. The site renders markdown docs into a Next.js web app. + +## Tech stack + +- **Monorepo**: pnpm workspaces + Turborepo +- **Framework**: Next.js (React 19) +- **Apps**: `apps/www` (main site, port 3000), `apps/icn` (ICN site, port 3001) +- **Shared package**: `packages/shared` — common components/utilities used by both apps +- **Node**: 24.x, **pnpm**: 9.1.2 + +## Repository layout + +``` +apps/ + www/ # Main docs site + docs/en/ # English markdown docs + docs/zh/ # Chinese markdown docs + public/docs/img/ # Doc images (local, .webp) + public/docs/file/ # Doc assets (PDFs, etc.) + icn/ # ICN docs site + docs/en/ # English markdown docs + public/docs/img/ # Doc images + public/docs/file/ # Doc assets +packages/ + shared/ # Shared components/utilities +scripts/ + check-images.sh # Image integrity checker (see below) +``` + +## Docs structure + +- Every folder has a `README.md` +- Folders and files (except README.md) use **numbered prefixes** (`1-introduction/`, `2-reward-mechanism.md`) +- **Kebab-case** for all file/folder names +- Content is GitHub-flavored Markdown with KaTeX math support + +## Images and assets + +- Local images use **bare filenames** in markdown: `![alt](image.webp)` — no path prefix +- Image files live in `apps/{app}/public/docs/img/` (flat, no subdirectories currently) +- Asset files (PDFs) live in `apps/{app}/public/docs/file/` +- External images use full URLs: `![alt](https://...)` +- No `` HTML tags — markdown syntax only + +## Commands + +| Command | Description | +|---------|-------------| +| `pnpm install` | Install dependencies | +| `pnpm dev` | Start all apps in dev mode (Turbo) | +| `pnpm build` | Build all apps (Turbo) | +| `pnpm tsc` | Type-check all apps | +| `pnpm lint` | Lint with ESLint | +| `pnpm fix` | Auto-fix lint issues | +| `pnpm check:images` | Check for orphaned/missing images across all apps | + +## CI checks + +- **check-images** (`.github/workflows/check-images.yml`): Runs on PRs to `main`. Fails if any app has orphaned images (file exists but no markdown references it) or missing images (markdown references a file that doesn't exist). Run locally with `pnpm check:images`. + +## Key conventions + +- All doc images should be `.webp` format +- When adding images: place the file in the correct app's `public/docs/img/` and reference it by bare filename in markdown +- When removing images: remove both the file and all markdown references +- When renaming images: update all markdown references across all locale folders (`en/`, `zh/`) +- The `check:images` script will catch any mismatches between referenced and actual images diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 02a3230..805281a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,15 @@ Use standard markdown image syntax: `![alt text](url)` | External image | Full URL | `![diagram](https://example.com/diagram.png)` | | Local image | Filename only (file lives in `public/docs/img/`) | `![GLIF Logo](logo.webp)` | +### Image integrity check + +Run `pnpm check:images` to verify all images are consistent. The script checks every app for: + +- **Missing images**: referenced in markdown but the file doesn't exist in `public/docs/img/` +- **Orphaned images**: file exists in `public/docs/img/` but no markdown references it + +This check also runs automatically on PRs to `main` via GitHub Actions and will block merge on failure. Always run it locally before pushing image-related changes. + ## Links Use standard markdown link syntax: `[text](url)` From 8b573a61ee346a8ff3043cd95ab29d7f8103be8f Mon Sep 17 00:00:00 2001 From: Thijs van Hoof Date: Thu, 19 Mar 2026 13:24:11 +0100 Subject: [PATCH 2/4] Update CLAUDE.md --- CLAUDE.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 40d058e..83e37c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,28 +9,22 @@ Documentation site for [GLIF](https://www.glif.io), a DeFi protocol on Filecoin. ## Tech stack - **Monorepo**: pnpm workspaces + Turborepo -- **Framework**: Next.js (React 19) -- **Apps**: `apps/www` (main site, port 3000), `apps/icn` (ICN site, port 3001) -- **Shared package**: `packages/shared` — common components/utilities used by both apps -- **Node**: 24.x, **pnpm**: 9.1.2 +- **Framework**: Next.js +- **Apps**: each subdirectory under `apps/` is a separate Next.js site (check `apps/*/package.json` for ports and details) +- **Shared package**: `packages/shared` — common components/utilities used by all apps +- Node and pnpm versions are specified in the root `package.json` ## Repository layout ``` apps/ - www/ # Main docs site - docs/en/ # English markdown docs - docs/zh/ # Chinese markdown docs - public/docs/img/ # Doc images (local, .webp) - public/docs/file/ # Doc assets (PDFs, etc.) - icn/ # ICN docs site - docs/en/ # English markdown docs + {app}/ # Each app is a Next.js docs site + docs/{locale}/ # Markdown docs per locale (e.g. en/, zh/) public/docs/img/ # Doc images - public/docs/file/ # Doc assets + public/docs/file/ # Doc assets (PDFs, etc.) packages/ shared/ # Shared components/utilities -scripts/ - check-images.sh # Image integrity checker (see below) +scripts/ # Repo-wide scripts (e.g. check-images.sh) ``` ## Docs structure @@ -66,7 +60,7 @@ scripts/ ## Key conventions -- All doc images should be `.webp` format +- Prefer `.webp` format for doc images - When adding images: place the file in the correct app's `public/docs/img/` and reference it by bare filename in markdown - When removing images: remove both the file and all markdown references - When renaming images: update all markdown references across all locale folders (`en/`, `zh/`) From 673b014c7e53289a1adb24b3f5726b9cdf090b5f Mon Sep 17 00:00:00 2001 From: Thijs van Hoof Date: Thu, 19 Mar 2026 13:34:55 +0100 Subject: [PATCH 3/4] Update CLAUDE.md --- CLAUDE.md | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 83e37c8..1672a8c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,20 +27,15 @@ packages/ scripts/ # Repo-wide scripts (e.g. check-images.sh) ``` -## Docs structure +## Writing docs -- Every folder has a `README.md` -- Folders and files (except README.md) use **numbered prefixes** (`1-introduction/`, `2-reward-mechanism.md`) -- **Kebab-case** for all file/folder names -- Content is GitHub-flavored Markdown with KaTeX math support +See `CONTRIBUTING.md` for markdown syntax rules, image/link conventions, and supported features (math, blockquote alerts, etc.). Read it before editing any markdown files. ## Images and assets -- Local images use **bare filenames** in markdown: `![alt](image.webp)` — no path prefix -- Image files live in `apps/{app}/public/docs/img/` (flat, no subdirectories currently) +- Image files live in `apps/{app}/public/docs/img/` - Asset files (PDFs) live in `apps/{app}/public/docs/file/` -- External images use full URLs: `![alt](https://...)` -- No `` HTML tags — markdown syntax only +- Markdown references images by **bare filename** — the repo layout above shows where the actual files go ## Commands @@ -57,11 +52,3 @@ scripts/ # Repo-wide scripts (e.g. check-images.sh) ## CI checks - **check-images** (`.github/workflows/check-images.yml`): Runs on PRs to `main`. Fails if any app has orphaned images (file exists but no markdown references it) or missing images (markdown references a file that doesn't exist). Run locally with `pnpm check:images`. - -## Key conventions - -- Prefer `.webp` format for doc images -- When adding images: place the file in the correct app's `public/docs/img/` and reference it by bare filename in markdown -- When removing images: remove both the file and all markdown references -- When renaming images: update all markdown references across all locale folders (`en/`, `zh/`) -- The `check:images` script will catch any mismatches between referenced and actual images From 3c66a862bb944e5524d5992100d07c26b3d1870d Mon Sep 17 00:00:00 2001 From: Thijs van Hoof Date: Thu, 19 Mar 2026 13:35:37 +0100 Subject: [PATCH 4/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 805281a..4d19979 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,12 @@ Use standard markdown image syntax: `![alt text](url)` | External image | Full URL | `![diagram](https://example.com/diagram.png)` | | Local image | Filename only (file lives in `public/docs/img/`) | `![GLIF Logo](logo.webp)` | +When working with images: +- Prefer `.webp` format +- When adding: place the file in the correct app's `public/docs/img/` and reference it by bare filename in markdown +- When removing: remove both the file and all markdown references +- When renaming: update all markdown references across all locale folders (e.g. `en/`, `zh/`) + ### Image integrity check Run `pnpm check:images` to verify all images are consistent. The script checks every app for: