64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
ReadMD is a Chrome extension that extracts webpage content and exports it as Markdown files. Built with React, TypeScript, and Vite using Chrome Extension Manifest V3.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development server (with HMR)
|
|
npm run dev
|
|
|
|
# Build extension for production
|
|
npm run build
|
|
|
|
# The dist/ folder is loaded in Chrome via chrome://extensions/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Chrome Extension Components
|
|
|
|
- **Content Script** (`src/content/index.ts`): Injected into web pages to extract content
|
|
- Uses `@mozilla/readability` to parse page content (runs on cloned DOM to avoid modifying original page)
|
|
- Uses `turndown` to convert HTML to Markdown
|
|
- Handles messages from popup via `chrome.runtime.onMessage`
|
|
- Injects highlight styles dynamically (not via CSS import) to avoid affecting page styles
|
|
|
|
- **Popup** (`src/popup/Popup.tsx`): Extension's main UI
|
|
- Triggers content extraction via `chrome.tabs.sendMessage`
|
|
- Shows preview, copy to clipboard, download options
|
|
- Auto-closes after copy/download operations
|
|
|
|
- **Background Service Worker** (`src/background/index.ts`): Handles extension events
|
|
|
|
### Content Script Communication
|
|
|
|
```typescript
|
|
// Popup sends message to content script
|
|
chrome.tabs.sendMessage(tabId, { action: 'extract' | 'extractSelection' | 'preview' | 'cleanup' })
|
|
|
|
// Content script responds
|
|
chrome.runtime.sendMessage({ success: true, data: ExtractedContent })
|
|
```
|
|
|
|
### Key Types (`src/types/index.ts`)
|
|
|
|
- `ExtractedContent`: Contains title, url, content (HTML), markdown, excerpt
|
|
- `ChromeMessage`: Actions: extract, extractSelection, preview, cleanup, copy, download
|
|
- `ContentScriptResponse`: Response structure from content script
|
|
|
|
### Important Implementation Details
|
|
|
|
1. **DOM Preservation**: Always use `document.cloneNode(true)` before passing to Readability - Readability's `parse()` modifies the DOM directly, so operating on a clone prevents page modification.
|
|
|
|
2. **Style Isolation**: Content script styles are injected via JavaScript (`document.createElement('style')`) not imported CSS files. Always call `cleanupHighlightStyles()` after extraction.
|
|
|
|
3. **Extension Loading**: Uses crxjs/vite-plugin which handles manifest generation. Content script uses loader pattern - `assets/index.ts-loader-*.js` loads the actual content script dynamically.
|