readmd/CLAUDE.md

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

# 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

// 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.