This repository was archived by the owner on Apr 13, 2026. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 0
docs: add CLAUDE.md with comprehensive codebase documentation #113
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,249 @@ | ||||||
| # CLAUDE.md | ||||||
|
|
||||||
| This file provides guidance for AI assistants working with the DevMDX codebase. | ||||||
|
|
||||||
| ## Project Overview | ||||||
|
|
||||||
| DevMDX is an MDX-powered blog and portfolio template built with Next.js 16, React 19, TypeScript, Tailwind CSS v4, and shadcn/ui. It renders MDX files from the `data/` directory as blog posts, project pages, community contributions, work history, and education pages. The project focuses on performance, SEO, and developer experience. | ||||||
|
|
||||||
| ## Tech Stack | ||||||
|
|
||||||
| - **Framework**: Next.js 16 (App Router, React Server Components) | ||||||
| - **Language**: TypeScript (strict mode) | ||||||
| - **Styling**: Tailwind CSS v4 with `@tailwindcss/postcss`, shadcn/ui (radix-vega style) | ||||||
| - **Content**: MDX via `@next/mdx` and `next-mdx-remote` | ||||||
| - **Validation**: Zod v4 for frontmatter schema validation | ||||||
| - **Package Manager**: pnpm 10.26.1 (enforced via `packageManager` field) | ||||||
| - **Node.js**: ^24.0.0 (enforced via `engines` field) | ||||||
| - **Fonts**: Google Sans Flex (sans) and Google Sans Code (mono) | ||||||
| - **Icons**: lucide-react | ||||||
| - **Theming**: next-themes (dark/light/system) | ||||||
|
|
||||||
| ## Commands | ||||||
|
|
||||||
| ```bash | ||||||
| pnpm install # Install dependencies | ||||||
| pnpm dev # Start dev server (default port 3001) | ||||||
| pnpm build # Production build (next build) | ||||||
| pnpm start # Start production server (default port 3001) | ||||||
| pnpm lint # Run ESLint (next lint) | ||||||
| pnpm lint:fix # Run ESLint with auto-fix | ||||||
| pnpm typecheck # TypeScript type checking (tsc --noEmit) | ||||||
| pnpm format # ESLint fix + Prettier format | ||||||
| pnpm analyze # Bundle analysis build | ||||||
| ``` | ||||||
|
|
||||||
| The `dev` and `start` scripts load `.env.local` and `.env` files before running Next.js. | ||||||
|
|
||||||
| ## Project Structure | ||||||
|
|
||||||
| ``` | ||||||
| devmdx/ | ||||||
| ├── src/ | ||||||
| │ ├── app/ # Next.js App Router pages | ||||||
| │ │ ├── layout.tsx # Root layout (fonts, providers, metadata) | ||||||
| │ │ ├── page.tsx # Home page | ||||||
| │ │ ├── globals.css # Global styles + Tailwind + hljs themes | ||||||
| │ │ ├── [article]/ # Dynamic article routes (slug configurable) | ||||||
| │ │ ├── projects/ # Project listing and detail pages | ||||||
| │ │ ├── community/ # Community contributions pages | ||||||
| │ │ ├── work/ # Work experience pages | ||||||
| │ │ ├── education/ # Education pages | ||||||
| │ │ ├── about/ # About page | ||||||
| │ │ ├── cover/ # Cover letter page | ||||||
| │ │ ├── sitemap.ts # Dynamic sitemap generation | ||||||
| │ │ ├── robots.ts # Dynamic robots.txt generation | ||||||
| │ │ └── feed.xml/route.ts # RSS feed route handler | ||||||
| │ ├── components/ | ||||||
| │ │ ├── article/ # Article-specific UI components | ||||||
| │ │ ├── community/ # Community section components | ||||||
| │ │ ├── common/ # Shared components (date-range, tag-button, etc.) | ||||||
| │ │ ├── education/ # Education section components | ||||||
| │ │ ├── helpers/ # Data fetching, config, metadata, utilities | ||||||
| │ │ ├── layout/ # Header, footer, client layout wrapper | ||||||
| │ │ ├── projects/ # Project section components | ||||||
| │ │ ├── providers.tsx # Theme provider (next-themes) | ||||||
| │ │ └── work/ # Work experience components | ||||||
| │ └── types/ # TypeScript types + Zod schemas | ||||||
| │ ├── article.ts # ArticleSchema, Article, ArticleFrontmatter | ||||||
| │ ├── project.ts # ProjectSchema, Project | ||||||
| │ ├── community.ts # CommunitySchema, Community | ||||||
| │ ├── work.ts # WorkExperienceSchema, WorkExperience | ||||||
| │ ├── education.ts # EducationSchema, Education | ||||||
| │ ├── config.ts # ConfigData, ConfigSeoData, etc. | ||||||
| │ └── user-profile.ts # Profile, SocialLinks | ||||||
| ├── data/ # Content and configuration (MDX + TS) | ||||||
| │ ├── articles/ # Blog articles organized by year (e.g., 2024/) | ||||||
| │ ├── projects/ # Project MDX files organized by year | ||||||
| │ ├── community/ # Community contribution MDX files | ||||||
| │ ├── work/ # Work experience MDX files | ||||||
| │ ├── education/ # Education MDX files | ||||||
| │ ├── config/index.ts # Site-wide configuration (SEO, nav, analytics) | ||||||
| │ └── profile/ # User profile data + markdown content | ||||||
| │ ├── index.ts # Profile object (name, email, socials) | ||||||
| │ ├── intro.md # Home page intro text | ||||||
| │ ├── about.md # About page content | ||||||
| │ └── cover.md # Cover letter content | ||||||
| ├── components/ | ||||||
| │ └── ui/ # shadcn/ui components (auto-generated) | ||||||
| ├── layouts/ # Layout containers (content, header, footer) | ||||||
| ├── lib/ | ||||||
| │ ├── utils.ts # cn() utility (clsx + tailwind-merge) | ||||||
| │ └── markdown/ # Custom markdown parser utilities | ||||||
| ├── scripts/ | ||||||
| │ ├── dev.sh # Dev server startup with env loading | ||||||
| │ └── start.sh # Production server startup with env loading | ||||||
| └── public/ # Static assets (favicon, cover image) | ||||||
| ``` | ||||||
|
|
||||||
| ## Path Aliases | ||||||
|
|
||||||
| Defined in `tsconfig.json`: | ||||||
|
|
||||||
| | Alias | Maps to | | ||||||
| |-------|---------| | ||||||
| | `@/*` | `./src/*` | | ||||||
| | `@/data/*` | `./data/*` | | ||||||
| | `@workspace/ui/components/*` | `./components/ui/*` | | ||||||
| | `@workspace/ui/lib/*` | `./lib/*` | | ||||||
| | `@workspace/ui/hooks/*` | `./hooks/*` | | ||||||
| | `@workspace/ui/layouts/*` | `./layouts/*` | | ||||||
|
|
||||||
| ## Architecture Patterns | ||||||
|
|
||||||
| ### Content System | ||||||
|
|
||||||
| All content lives in the `data/` directory as MDX files. Each content type (articles, projects, community, work, education) follows this pattern: | ||||||
|
|
||||||
| 1. **MDX files** with YAML frontmatter in `data/<type>/` (articles are organized by year subdirectories) | ||||||
| 2. **Zod schemas** in `src/types/<type>.ts` validate frontmatter at read time | ||||||
| 3. **Helper functions** in `src/components/helpers/<type>.tsx` handle file reading, parsing, and indexing | ||||||
| 4. **Slug derivation**: slugs come from frontmatter `slug` field or fall back to the filename (sanitized) | ||||||
|
|
||||||
| Articles use `gray-matter` for frontmatter parsing, `next-mdx-remote` for MDX compilation with `remark-gfm`, `rehype-slug`, and `rehype-autolink-headings`. | ||||||
|
|
||||||
| ### Configuration | ||||||
|
|
||||||
| - **Site config** (`data/config/index.ts`): SEO settings, analytics IDs, navigation toggles, content labels, and misc settings. Typed by `ConfigData` interface. | ||||||
| - **Profile** (`data/profile/index.ts`): User profile data (name, email, social links). Typed by `Profile` interface. | ||||||
| - **Environment config** (`src/components/helpers/env-config.ts`): Runtime config from environment variables for base URL, image hostnames, CSP, and robots settings. | ||||||
|
|
||||||
| ### Environment Variables | ||||||
|
|
||||||
| | Variable | Purpose | | ||||||
| |----------|---------| | ||||||
| | `NEXT_PUBLIC_BASE_URL` | Site base URL for metadata/OG tags | | ||||||
| | `NEXT_PUBLIC_ALLOWED_IMAGE_HOSTNAMES` | Comma-separated allowed image hostnames | | ||||||
| | `NEXT_PUBLIC_ALLOWED_HOSTNAMES` | Comma-separated allowed hostnames for CSP | | ||||||
| | `NEXT_PUBLIC_ALLOW_ROBOTS` | Set to `"true"` to allow search engine indexing | | ||||||
| | `PORT` | Server port (default: 3001) | | ||||||
|
|
||||||
| ### Routing | ||||||
|
|
||||||
| The App Router uses dynamic segments. The article route segment `[article]` is configurable via `configData.misc.content.articleSlug` (defaults to `"articles"`). Key routes: | ||||||
|
|
||||||
| - `/` — Home (intro markdown + recent articles) | ||||||
| - `/<articleSlug>/<year>/<slug>` — Article detail | ||||||
| - `/projects/<slug>` — Project detail | ||||||
| - `/community/<year>/<slug>` — Community contribution detail | ||||||
| - `/work/<slug>` — Work experience detail | ||||||
| - `/education/<slug>` — Education detail | ||||||
| - `/about`, `/cover` — Static content pages | ||||||
| - `/sitemap.xml`, `/feed.xml`, `/robots.txt` — SEO routes | ||||||
|
|
||||||
| ### Component Organization | ||||||
|
|
||||||
| - **UI primitives** (`components/ui/`): shadcn/ui components. These are auto-generated — do not manually modify. | ||||||
| - **Layout containers** (`layouts/`): Page-level wrappers for header, content, and footer. | ||||||
| - **Feature components** (`src/components/<feature>/`): Domain-specific components grouped by content type. | ||||||
| - **Helper modules** (`src/components/helpers/`): Data access, URL building, metadata generation, config access. These are server-side modules using `fs` and should not be imported in client components. | ||||||
| - **Providers** (`src/components/providers.tsx`): Client-side theme provider wrapper. | ||||||
|
|
||||||
| ### Metadata and SEO | ||||||
|
|
||||||
| Every page generates metadata via `createPageMetadata()` from `src/components/helpers/metadata.ts`. This produces OpenGraph, Twitter Card, and Apple Web App metadata. Structured data (JSON-LD) is added via the `StructuredData` component. | ||||||
|
|
||||||
| ## Code Conventions | ||||||
|
|
||||||
| ### TypeScript | ||||||
|
|
||||||
| - Strict mode enabled | ||||||
| - Use Zod schemas for all content frontmatter validation | ||||||
| - Types exported alongside their schemas from `src/types/` | ||||||
| - Prefer `type` over `interface` for data shapes (project convention) | ||||||
|
||||||
| - Prefer `type` over `interface` for data shapes (project convention) | |
| - Use `type` for Zod-inferred types and content models (articles, projects, community, work, education), and use `interface` for configuration objects (e.g., `ConfigData`, `ConfigAnalyticsData`, `ConfigSeoData`, `Profile`, `SocialLinks`). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The statement that "UI primitives (
components/ui/): shadcn/ui components. These are auto-generated — do not manually modify" is inaccurate. While many components in this directory are indeed shadcn/ui components, several are custom components includingmarkdown.tsx(558 lines),code-block.tsx(374 lines),structured-data.tsx,theme-switcher.tsx,prefetch-link.tsx,empty-state.tsx, andspinner.tsx. This statement should be revised to clarify that the directory contains both auto-generated shadcn/ui components and custom UI components.