Initial commit: TypoGenie - Markdown to Word document converter
This commit is contained in:
TypoGenie
163
AGENTS.md
Normal file
163
AGENTS.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# TypoGenie - AI Coding Agent Guide
|
||||
|
||||
## Project Overview
|
||||
|
||||
TypoGenie is a web application that transforms Markdown content into professionally formatted Microsoft Word documents. Users upload `.md` or `.txt` files, select from 40+ typography styles across multiple categories (Minimalist, Corporate, Editorial, Tech, Creative, etc.), and download a formatted `.docx` file.
|
||||
|
||||
The application uses a local Markdown parser (marked) rather than AI for document conversion, though it was originally designed with AI integration in mind.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Framework**: React 19.2.4 with TypeScript 5.8.2
|
||||
- **Build Tool**: Vite 6.2.0
|
||||
- **Styling**: Tailwind CSS (loaded via CDN in `index.html`)
|
||||
- **Icons**: Lucide React
|
||||
- **Document Generation**: docx library (client-side DOCX creation)
|
||||
- **Markdown Parsing**: marked library (local conversion, no API calls)
|
||||
- **Fonts**: Google Fonts loaded dynamically
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── App.tsx # Main application component with state machine
|
||||
├── index.tsx # React root mount
|
||||
├── index.html # HTML entry, Tailwind CDN, import maps
|
||||
├── types.ts # TypeScript interfaces (StyleOption, DocxStyleConfig, etc.)
|
||||
├── constants.ts # System prompts and style exports
|
||||
├── components/
|
||||
│ ├── FileUpload.tsx # Drag-and-drop file upload (.md, .txt)
|
||||
│ ├── StyleSelector.tsx # Style grid with preview iframe
|
||||
│ ├── Preview.tsx # Final preview and DOCX export
|
||||
│ └── StylePreviewModal.tsx # (Unused) Modal style preview component
|
||||
|
||||
├── styles/ # Typography style definitions
|
||||
│ ├── index.ts # Aggregates all style categories
|
||||
│ ├── minimalist.ts # 11 minimalist styles
|
||||
│ ├── corporate.ts # 13 corporate/professional styles
|
||||
│ ├── editorial.ts # Editorial/magazine styles
|
||||
│ ├── tech.ts # Tech/startup styles
|
||||
│ ├── creative.ts # Creative/artistic styles
|
||||
│ ├── vintage.ts # Retro/vintage styles
|
||||
│ ├── lifestyle.ts # Lifestyle/blog styles
|
||||
│ ├── academic.ts # Academic/research styles
|
||||
│ └── industrial.ts # Industrial/technical styles
|
||||
```
|
||||
|
||||
## Application State Flow
|
||||
|
||||
The app uses a 4-state machine defined in `types.ts`:
|
||||
|
||||
1. **UPLOAD** - Initial screen with file upload dropzone
|
||||
2. **CONFIG** - Style selection interface with live preview
|
||||
3. **GENERATING** - Processing animation (800ms artificial delay for UX)
|
||||
4. **PREVIEW** - Final preview with DOCX download option
|
||||
|
||||
State transitions:
|
||||
- UPLOAD → CONFIG: After file loaded successfully
|
||||
- CONFIG → GENERATING: When user clicks "Apply Style & Convert"
|
||||
- GENERATING → PREVIEW: After HTML generation completes
|
||||
- PREVIEW → CONFIG: Via "Back to Editor" button
|
||||
- Any → UPLOAD: Via header logo click (reset)
|
||||
|
||||
## Style System Architecture
|
||||
|
||||
Each style is a `StyleOption` object containing:
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: string, // Unique identifier
|
||||
name: string, // Display name
|
||||
category: string, // For filtering (Minimalist, Corporate, etc.)
|
||||
description: string, // Short description
|
||||
vibe: string, // Mood/aesthetic descriptor
|
||||
googleFontsImport: string, // Google Fonts URL
|
||||
wordConfig: {
|
||||
heading1: DocxStyleConfig, // H1 formatting for Word
|
||||
heading2: DocxStyleConfig, // H2 formatting for Word
|
||||
body: DocxStyleConfig, // Body text formatting for Word
|
||||
accentColor: string // Brand accent color
|
||||
},
|
||||
previewCss: string // CSS string for web preview (must manually match wordConfig)
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: `wordConfig` and `previewCss` must be kept in sync manually for visual fidelity between preview and exported document.
|
||||
|
||||
## Build Commands
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Development server (runs on port 3000)
|
||||
npm run dev
|
||||
|
||||
# Production build (outputs to dist/)
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
No environment variables required. The app uses local Markdown parsing only.
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### DOCX Generation (components/Preview.tsx)
|
||||
|
||||
The DOCX export uses the `docx` library to create Word-compatible documents:
|
||||
|
||||
- Converts HTML to docx Paragraph elements
|
||||
- Supports headings (h1-h6), paragraphs, blockquotes, lists
|
||||
- Applies style-specific fonts, colors, spacing, borders, and shading
|
||||
- Paper sizes: A4 (210mm × 297mm) and Letter (8.5in × 11in)
|
||||
- Margins: 1in top/bottom, 1.2in left/right
|
||||
|
||||
### Preview System
|
||||
|
||||
Previews render in an iframe with dynamically injected:
|
||||
- Google Fonts link from style config
|
||||
- Style-specific CSS from `previewCss`
|
||||
- Sample content for style selection view
|
||||
- Actual converted content for final preview
|
||||
|
||||
### File Upload
|
||||
|
||||
Accepts: `.md`, `.txt`, `.markdown`
|
||||
Uses FileReader API for client-side text extraction
|
||||
Validates file extension before processing
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
- **TypeScript**: Strict mode enabled; all components typed with React.FC
|
||||
- **Imports**: Use `@/` path alias for project root imports
|
||||
- **Styling**: Tailwind utility classes; custom CSS only in `previewCss` fields
|
||||
- **Naming**: PascalCase for components, camelCase for functions/variables
|
||||
- **Comments**: Explain business logic and non-obvious decisions
|
||||
|
||||
## Adding New Typography Styles
|
||||
|
||||
1. Choose appropriate category file in `/styles/` (or create new category)
|
||||
2. Add StyleOption object to the array with:
|
||||
- Unique `id`
|
||||
- Google Fonts URL
|
||||
- Complete `wordConfig` for DOCX export
|
||||
- Matching `previewCss` for web preview
|
||||
3. Export from `/styles/index.ts` if new category
|
||||
4. Test both preview and DOCX export
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- No server-side processing; all conversion happens client-side
|
||||
- No API keys required; all processing is done locally
|
||||
- File upload limited to text files by extension check
|
||||
- iframe sandboxing for style previews (same-origin content only)
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- `wordConfig` and `previewCss` require manual synchronization
|
||||
- DOCX export has limited table support
|
||||
- Complex Markdown (nested lists, code blocks) may not format perfectly
|
||||
- Style categories are loosely organized and may overlap
|
||||
Reference in New Issue
Block a user