From 51272b30356c6ccd4dac7d969bff76f07adfb17f Mon Sep 17 00:00:00 2001
From: ddshi <8811906+ddshi@user.noreply.gitee.com>
Date: Fri, 23 Jan 2026 15:15:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0CLAUDE.md=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e204efa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,63 @@
+# 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.