|
|
@@ -1,289 +0,0 @@
|
|
|
-# WARP.md
|
|
|
-
|
|
|
-This file provides guidance to WARP (warp.dev) when working with code in this repository.
|
|
|
-
|
|
|
-## Project Overview
|
|
|
-
|
|
|
-"The gooneral wheelchair" is a full-stack personal CMS (Content Management System) built with React frontend and Node.js/Express backend. The system provides both a public blog interface and a complete admin dashboard for managing posts dynamically through a REST API.
|
|
|
-
|
|
|
-## Development Commands
|
|
|
-
|
|
|
-### Full-Stack Development
|
|
|
-- **Start both servers**: `npm run dev` - Runs both frontend (Vite) and backend (Express) servers concurrently
|
|
|
-- **Frontend only**: `npm run dev:frontend` - Runs Vite dev server on port 5173
|
|
|
-- **Backend only**: `npm run dev:backend` - Runs Express API server on port 3001
|
|
|
-
|
|
|
-### Production Commands
|
|
|
-- **Build frontend**: `npm run build` - Creates optimized production build in `dist/`
|
|
|
-- **Start backend**: `npm run start:backend` - Starts production Express server
|
|
|
-- **Preview frontend**: `npm run preview` - Serves the built application locally
|
|
|
-
|
|
|
-### Code Quality
|
|
|
-- **Lint code**: `npm run lint` - Runs ESLint on all JavaScript/JSX files
|
|
|
-
|
|
|
-### Package Management
|
|
|
-- **Install all dependencies**: `npm install && cd backend && npm install`
|
|
|
-- **Add frontend dependency**: `npm install <package-name>`
|
|
|
-- **Add backend dependency**: `cd backend && npm install <package-name>`
|
|
|
-- **Add dev dependency**: `npm install -D <package-name>`
|
|
|
-
|
|
|
-## Architecture Overview
|
|
|
-
|
|
|
-### Full-Stack Architecture
|
|
|
-- **Frontend**: React SPA with React Router for navigation
|
|
|
-- **Backend**: Node.js/Express API server with REST endpoints
|
|
|
-- **Database**: File-system based (markdown files in `public/posts/`)
|
|
|
-- **Communication**: Frontend communicates with backend via REST API calls
|
|
|
-
|
|
|
-### Frontend Structure
|
|
|
-- **Entry Point**: `src/main.jsx` - React application entry with StrictMode
|
|
|
-- **Main Router**: `src/App.jsx` - React Router setup with route definitions
|
|
|
-- **Components**:
|
|
|
- - `BlogHome` - Public blog homepage with post grid
|
|
|
- - `PostView` - Individual post display component
|
|
|
- - `AdminDashboard` - Admin interface for managing posts
|
|
|
- - `PostEditor` - Create/edit post interface with live preview
|
|
|
-- **Styling**: Tailwind CSS 4.x via Vite plugin
|
|
|
-
|
|
|
-### Backend API Structure
|
|
|
-- **Server**: `backend/server.js` - Express server with CORS and session management
|
|
|
-- **Authentication**: Session-based authentication with bcrypt password hashing
|
|
|
-- **API Base URL**: `http://localhost:3001/api`
|
|
|
-- **Public Endpoints**:
|
|
|
- - `GET /api/posts` - Fetch all posts with metadata
|
|
|
- - `GET /api/posts/:slug` - Fetch specific post
|
|
|
- - `GET /api/health` - Health check endpoint
|
|
|
-- **Authentication Endpoints**:
|
|
|
- - `POST /api/auth/login` - User login
|
|
|
- - `POST /api/auth/logout` - User logout
|
|
|
- - `GET /api/auth/me` - Get current user info
|
|
|
- - `POST /api/auth/change-password` - Change user password (requires auth)
|
|
|
-- **Protected Endpoints** (require admin authentication):
|
|
|
- - `POST /api/posts` - Create new post
|
|
|
- - `PUT /api/posts/:slug` - Update existing post
|
|
|
- - `DELETE /api/posts/:slug` - Delete post
|
|
|
-
|
|
|
-### Content Management System
|
|
|
-The CMS operates on a hybrid approach:
|
|
|
-
|
|
|
-1. **Post Storage**: Markdown files in `public/posts/` directory
|
|
|
-2. **API Layer**: Express server handles CRUD operations on markdown files
|
|
|
-3. **Dynamic Index**: Backend automatically generates `index.json` when posts change
|
|
|
-4. **Metadata Handling**: Server-side parsing of frontmatter (`title:`, `desc:`, `tags:`)
|
|
|
-5. **Admin Interface**: Full CRUD interface accessible at `/admin`
|
|
|
-
|
|
|
-### Markdown Processing Pipeline
|
|
|
-The application uses an extensive MarkdownIt setup with multiple plugins:
|
|
|
-
|
|
|
-- **Base Configuration**: HTML enabled, linkify, typographer
|
|
|
-- **Extensions**: Emoji, abbreviations, subscript/superscript, insertions, marks, definition lists, footnotes, spoilers
|
|
|
-- **Custom Containers**: Info, warning, and spoiler containers
|
|
|
-- **Table Enhancement**: Wraps tables in scrollable containers
|
|
|
-- **Sanitization**: DOMPurify for XSS protection
|
|
|
-
|
|
|
-### Client-Side Routing
|
|
|
-- Uses React Router for navigation
|
|
|
-- Route pattern: `/posts/{slug}` maps to post slugs
|
|
|
-- Home route `/` shows post grid
|
|
|
-- Admin routes under `/admin` for content management
|
|
|
-
|
|
|
-### Routing Structure
|
|
|
-**Frontend Routes**:
|
|
|
-- `/` - Blog homepage (BlogHome component)
|
|
|
-- `/posts/:slug` - Individual post view (PostView component)
|
|
|
-- `/login` - Login form (LoginForm component)
|
|
|
-- `/admin` - Admin dashboard (AdminDashboard component) - **Protected**
|
|
|
-- `/admin/post/new` - Create new post (PostEditor component) - **Protected**
|
|
|
-- `/admin/post/:slug/edit` - Edit existing post (PostEditor component) - **Protected**
|
|
|
-
|
|
|
-**API Routes**:
|
|
|
-- `GET /api/posts` - List all posts
|
|
|
-- `GET /api/posts/:slug` - Get single post
|
|
|
-- `POST /api/posts` - Create post
|
|
|
-- `PUT /api/posts/:slug` - Update post
|
|
|
-- `DELETE /api/posts/:slug` - Delete post
|
|
|
-
|
|
|
-## File Structure Patterns
|
|
|
-
|
|
|
-### Frontend Source Code
|
|
|
-- `src/App.jsx` - Main router component with route definitions and auth integration
|
|
|
-- `src/main.jsx` - React entry point
|
|
|
-- `src/index.css` - Global styles (Tailwind imports)
|
|
|
-- `src/contexts/AuthContext.jsx` - Authentication context and state management
|
|
|
-- `src/components/AdminDashboard.jsx` - Admin interface component
|
|
|
-- `src/components/PostEditor.jsx` - Post creation/editing interface
|
|
|
-- `src/components/LoginForm.jsx` - User login form
|
|
|
-- `src/components/ProtectedRoute.jsx` - Route protection wrapper
|
|
|
-
|
|
|
-### Backend Source Code
|
|
|
-- `backend/server.js` - Express API server with authentication
|
|
|
-- `backend/auth.js` - Authentication utilities and user management
|
|
|
-- `backend/users.json` - User data storage (auto-generated)
|
|
|
-- `backend/package.json` - Backend dependencies and scripts
|
|
|
-
|
|
|
-### Content
|
|
|
-- `public/posts/*.md` - Blog post markdown files (managed via API)
|
|
|
-- `public/posts/index.json` - Auto-generated file list (managed by backend)
|
|
|
-- `public/posts/image.png` - Post assets (images referenced in markdown)
|
|
|
-
|
|
|
-### Configuration
|
|
|
-- `package.json` - Frontend dependencies and development scripts
|
|
|
-- `backend/package.json` - Backend dependencies
|
|
|
-- `vite.config.js` - Vite configuration with React and Tailwind (no custom plugins)
|
|
|
-- `eslint.config.js` - ESLint configuration with React rules
|
|
|
-
|
|
|
-## Development Workflow
|
|
|
-
|
|
|
-### Adding New Posts
|
|
|
-**Via Admin Interface (Recommended)**:
|
|
|
-1. Navigate to `/admin` in your browser
|
|
|
-2. Click "New Post" button
|
|
|
-3. Fill in title, description, tags, and content
|
|
|
-4. Use the Preview tab to see rendered markdown
|
|
|
-5. Click "Create Post" to save
|
|
|
-
|
|
|
-**Manual File Creation**:
|
|
|
-1. Create new `.md` file in `public/posts/` directory
|
|
|
-2. Include frontmatter: `title: Your Title`, `desc: Description`, `tags: tag1, tag2`
|
|
|
-3. Write content using supported markdown extensions
|
|
|
-4. Restart backend server to recognize new file
|
|
|
-
|
|
|
-### Editing Posts
|
|
|
-**Via Admin Interface**:
|
|
|
-1. Go to `/admin` and click "Edit" on any post
|
|
|
-2. Modify content in the editor with live preview
|
|
|
-3. Click "Update Post" to save changes
|
|
|
-
|
|
|
-**Direct File Editing**:
|
|
|
-1. Edit the `.md` file directly in `public/posts/`
|
|
|
-2. Changes will be reflected immediately via API
|
|
|
-
|
|
|
-### Markdown Features Supported
|
|
|
-**WYSIWYG Editor Features**:
|
|
|
-- **Visual toolbar**: Quick access to formatting (bold, italic, headers, lists, links, images, code)
|
|
|
-- **Multiple editing modes**: Edit, Preview, and Live (split) modes
|
|
|
-- **Syntax highlighting**: Enhanced code editing with monospace font
|
|
|
-- **Drag-to-resize**: Adjustable panes in live mode
|
|
|
-
|
|
|
-**Standard Markdown Syntax Support**:
|
|
|
-- **Text formatting**: Bold, italic, strikethrough
|
|
|
-- **Headers**: All levels (H1-H6)
|
|
|
-- **Lists**: Ordered and unordered (with nesting)
|
|
|
-- **Links and images**: Standard `[text](url)` and `` syntax
|
|
|
-- **Code**: Inline `code` and fenced code blocks with syntax highlighting
|
|
|
-- **Tables**: GitHub-style tables (automatically made scrollable)
|
|
|
-- **Blockquotes**: Standard `>` syntax, great for callouts with emoji
|
|
|
-- **Horizontal rules**: `---` or `***`
|
|
|
-- **HTML support**: Standard HTML tags when needed
|
|
|
-- **Emoji**: GitHub-style `:emoji_name:` syntax
|
|
|
-- **Footnotes**: Standard `[^ref]` syntax
|
|
|
-- **Collapsible content**: HTML `<details><summary>` tags
|
|
|
-- **Line breaks**: Proper paragraph handling
|
|
|
-
|
|
|
-### Code Style
|
|
|
-- Uses ESLint with React-specific rules
|
|
|
-- Unused variables allowed if they follow `^[A-Z_]` pattern
|
|
|
-- ES2020+ features enabled
|
|
|
-- JSX support configured
|
|
|
-
|
|
|
-### Markdown Compatibility
|
|
|
-- **Standards-compliant**: Uses only widely-supported markdown features
|
|
|
-- **Portable content**: Markdown files work with GitHub, GitLab, and other platforms
|
|
|
-- **No custom extensions**: Avoids proprietary syntax that doesn't work elsewhere
|
|
|
-- **HTML fallback**: When markdown isn't enough, standard HTML tags are supported
|
|
|
-
|
|
|
-## Custom Implementation Notes
|
|
|
-
|
|
|
-### State Management
|
|
|
-Each React component manages its own state with useState hooks:
|
|
|
-- **BlogHome**: `posts`, `loading`, `error` - For blog homepage
|
|
|
-- **PostView**: `post`, `loading`, `error` - For individual post display
|
|
|
-- **AdminDashboard**: `posts`, `loading`, `error` - For admin post list
|
|
|
-- **PostEditor**: `formData`, `loading`, `saving`, `error`, `previewMode` - For post editing
|
|
|
-
|
|
|
-### API Integration
|
|
|
-All components use fetch() to communicate with the Express backend:
|
|
|
-- **Base URL**: `http://localhost:3001/api`
|
|
|
-- **Error Handling**: Consistent error states across components
|
|
|
-- **Loading States**: All API calls show loading indicators
|
|
|
-- **CRUD Operations**: Full create, read, update, delete functionality
|
|
|
-
|
|
|
-### Unusual Function Names
|
|
|
-The codebase contains intentionally obscure function names (e.g., `giveFoxHerHeir`, `getTingyun`, `travelToExpress`, `conceiveFoxFromSemen`) - this appears to be a stylistic choice and should be preserved when making changes.
|
|
|
-
|
|
|
-### Content Processing
|
|
|
-- Metadata extracted via regex patterns from markdown content
|
|
|
-- HTML content sanitized with DOMPurify before rendering
|
|
|
-- Dynamic title updates based on selected post
|
|
|
-- Custom image credit parsing for blog post assets
|
|
|
-
|
|
|
-## Development Setup
|
|
|
-
|
|
|
-### Initial Setup
|
|
|
-1. Install frontend dependencies: `npm install`
|
|
|
-2. Install backend dependencies: `cd backend && npm install`
|
|
|
-3. Start development servers: `npm run dev`
|
|
|
-4. Frontend will be available at `http://localhost:5173`
|
|
|
-5. Backend API will be available at `http://localhost:3001`
|
|
|
-6. Admin interface accessible at `http://localhost:5173/admin`
|
|
|
-
|
|
|
-### Production Deployment
|
|
|
-**Frontend**: Can be deployed to static hosting (Netlify, Vercel, etc.)
|
|
|
-**Backend**: Requires Node.js server environment (Heroku, Railway, DigitalOcean, etc.)
|
|
|
-**Database**: File system based, no external database required
|
|
|
-
|
|
|
-### Environment Variables
|
|
|
-- `PORT` - Backend server port (default: 3001)
|
|
|
-- `NODE_ENV` - Environment mode for backend
|
|
|
-
|
|
|
-## Authentication System
|
|
|
-
|
|
|
-### Default Credentials
|
|
|
-- **Username**: `admin`
|
|
|
-- **Password**: `admin123`
|
|
|
-- **⚠️ IMPORTANT**: Change the default password immediately after first login
|
|
|
-
|
|
|
-### Security Features
|
|
|
-- Session-based authentication with secure cookies
|
|
|
-- Bcrypt password hashing (10 rounds)
|
|
|
-- Protected API endpoints require admin role
|
|
|
-- Frontend route protection with automatic redirects
|
|
|
-- Session timeout after 24 hours of inactivity
|
|
|
-
|
|
|
-### User Management
|
|
|
-- Single admin user system (expandable)
|
|
|
-- Password change functionality in admin interface
|
|
|
-- Automatic user file creation on first server start
|
|
|
-- Session persistence across browser sessions
|
|
|
-
|
|
|
-## Admin Interface Features
|
|
|
-
|
|
|
-### Authentication Flow
|
|
|
-1. Navigate to `/admin` without authentication → redirected to `/login`
|
|
|
-2. Login with credentials → redirected to intended admin page
|
|
|
-3. Admin navigation only visible when authenticated
|
|
|
-4. Logout clears session and redirects to homepage
|
|
|
-
|
|
|
-### Dashboard (`/admin`) - **Requires Authentication**
|
|
|
-- Overview statistics (total posts, recent posts)
|
|
|
-- Post management table with edit/delete actions
|
|
|
-- Quick access to create new posts
|
|
|
-- User greeting and logout functionality
|
|
|
-
|
|
|
-### Post Editor (`/admin/post/new` or `/admin/post/:slug/edit`) - **Requires Authentication**
|
|
|
-- Rich form interface for post metadata (title, description, tags)
|
|
|
-- **WYSIWYG Markdown Editor** with multiple editing modes:
|
|
|
- - **Edit Mode**: Source code editing with syntax highlighting
|
|
|
- - **Preview Mode**: Live rendered markdown preview
|
|
|
- - **Live Mode**: Split view with edit and preview side-by-side
|
|
|
-- Visual toolbar with formatting buttons (bold, italic, headers, lists, links, etc.)
|
|
|
-- Drag-to-resize editor panes in live mode
|
|
|
-- Full support for standard markdown features (tables, footnotes, emoji, HTML tags)
|
|
|
-- Save/cancel actions with error handling
|
|
|
-- Automatic slug generation from title for new posts
|
|
|
-
|
|
|
-### Login Form (`/login`)
|
|
|
-- Clean, responsive login interface
|
|
|
-- Error handling for invalid credentials
|
|
|
-- Default credentials display for initial setup
|
|
|
-- Automatic redirect after successful login
|
