Skip to content

Commit b03be3f

Browse files
harryisfishharryisfish
committed
docs: add CLAUDE.md documentation for project
1 parent 12421e0 commit b03be3f

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎CLAUDE.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
MultiPost Markdown Editor is a WeChat-focused Markdown editor that renders documents into WeChat-compatible HTML. It integrates with the MultiPost browser extension to publish content across multiple platforms (知乎, 微博, 小红书, 抖音).
8+
9+
Based on [doocs/md](https://github.com/doocs/md) with custom modifications.
10+
11+
## Dual Build Targets
12+
13+
This project builds **both a web application and a browser extension** from the same codebase:
14+
15+
### Web Application
16+
17+
- **Development**: `npm start` or `npm run dev`
18+
- **Build**: `npm run build` (deploys to `/md` directory)
19+
- **Build for root**: `npm run build:h5-netlify` (sets `SERVER_ENV=NETLIFY`, deploys to `/`)
20+
- **Preview**: `npm run preview`
21+
22+
### Browser Extension
23+
24+
- **Development**: `npm run ext:dev` (Chrome) or `npm run firefox:dev` (Firefox)
25+
- **Package**: `npm run ext:zip` or `npm run firefox:zip`
26+
- Entry point: `wxt.config.ts`
27+
- Extension entrypoints: `src/entrypoints/`
28+
29+
## Development Commands
30+
31+
```sh
32+
# Install dependencies
33+
npm i
34+
35+
# Start dev server (web app)
36+
npm start
37+
38+
# Build web app for /md path
39+
npm run build
40+
41+
# Build web app for root path
42+
npm run build:h5-netlify
43+
44+
# Type check
45+
npm run type-check
46+
47+
# Lint and auto-fix
48+
npm run lint
49+
50+
# Build extension for Chrome
51+
npm run ext:dev # Development
52+
npm run ext:zip # Package
53+
54+
# Build extension for Firefox
55+
npm run firefox:dev
56+
npm run firefox:zip
57+
58+
# Analyze bundle size
59+
npm run build:analyze
60+
```
61+
62+
## Architecture
63+
64+
### State Management (Pinia)
65+
66+
Two main stores in `src/stores/index.ts`:
67+
68+
1. **useStore**: Main application state
69+
- Editor content and CodeMirror instances (`editor`, `cssEditor`)
70+
- Theme/styling options (`theme`, `fontFamily`, `fontSize`, `primaryColor`, `codeBlockTheme`)
71+
- Content management (`posts`, `currentPostIndex`)
72+
- Feature toggles (`isMacCodeBlock`, `isCiteStatus`, `isCountStatus`, `isUseIndent`)
73+
- Actions for importing/exporting Markdown and HTML
74+
75+
2. **useDisplayStore**: UI visibility state
76+
- Dialog visibility (`isShowCssEditor`, `isShowInsertFormDialog`, `isShowUploadImgDialog`)
77+
78+
### Rendering Pipeline
79+
80+
The Markdown rendering flow (see `src/utils/renderer.ts`):
81+
82+
1. **Parse front matter** and extract metadata
83+
2. **Convert Markdown to HTML** using marked.js with custom renderer
84+
3. **Apply theme styles** based on user selections (fonts, colors, sizes)
85+
4. **Process special elements**:
86+
- Code blocks with highlight.js
87+
- Math equations with KaTeX
88+
- Mermaid diagrams
89+
- GFM alerts (via `src/utils/MDAlert.ts`)
90+
5. **Inject custom CSS** from the CSS editor
91+
6. **Sanitize output** with DOMPurify
92+
7. **Add WeChat-specific features**:
93+
- External link footnotes (when `isCiteStatus` is enabled)
94+
- Mac-style code block decorations
95+
- Reading time and word count statistics
96+
97+
### Component Structure
98+
99+
- **Main app**: `src/App.vue` → `src/views/CodemirrorEditor.vue`
100+
- **UI components**: `src/components/ui/` (Radix Vue components with Tailwind)
101+
- **Custom components**: `src/components/` (FormItem, CustomUploadForm, etc.)
102+
- **CodemirrorEditor**: `src/components/CodemirrorEditor/`
103+
104+
### Configuration & Build
105+
106+
- **Vite config**: `vite.config.ts`
107+
- Uses UnoCSS, auto-imports from Pinia/VueUse
108+
- Base path: `/md/` (default) or `/` (NETLIFY mode)
109+
- Polyfills for Node.js modules (path, util, stream, fs)
110+
111+
- **WXT config**: `wxt.config.ts` (browser extension)
112+
- Custom module: `src/modules/build-extension.ts`
113+
- Handles inline scripts (CSP compliance), chunking, HTML transformation
114+
115+
- **TypeScript**: Project references (`tsconfig.json` → `tsconfig.app.json`, `tsconfig.node.json`)
116+
117+
- **ESLint**: `eslint.config.mjs` using @antfu/eslint-config
118+
119+
### Auto-imports
120+
121+
The following are auto-imported (no need to import manually):
122+
123+
- Vue 3 APIs (ref, computed, onMounted, etc.)
124+
- Pinia (defineStore, storeToRefs, etc.)
125+
- VueUse composables (@vueuse/core)
126+
- Stores from `src/stores/`
127+
- Toast utilities from `src/utils/toast/`
128+
129+
### Theme System
130+
131+
Themes are defined in `src/config/index.ts` as `themeMap`:
132+
133+
- Each theme has `base`, `block`, and `inline` styles
134+
- Themes are merged with user preferences (font, size, color)
135+
- Custom CSS can override any theme via the CSS editor
136+
- Process: `css2json()` → `customCssWithTemplate()` → `customizeTheme()` → applied to renderer
137+
138+
### Content Storage
139+
140+
- Uses `useStorage()` from VueUse for localStorage persistence
141+
- All keys prefixed via `addPrefix()` function
142+
- Content stored as `posts` array with `{ title, content }`
143+
- CSS editor supports multiple tabs/schemes (`cssContentConfig`)
144+
145+
## Key Files
146+
147+
- `src/stores/index.ts` - State management
148+
- `src/utils/renderer.ts` - Markdown → HTML rendering engine
149+
- `src/utils/index.ts` - Utility functions (CSS parsing, export, formatting)
150+
- `src/config/index.ts` - Theme definitions and constants
151+
- `src/main.ts` - App entry point (web)
152+
- `src/modules/build-extension.ts` - Custom WXT module for extension builds
153+
- `wxt.config.ts` - Browser extension configuration
154+
- `vite.config.ts` - Web app build configuration
155+
156+
## Extension Integration
157+
158+
The browser extension and web app share most code but have different entry points:
159+
160+
- Web: `index.html` → `src/main.ts`
161+
- Extension options page: `index.html` (reused)
162+
- Extension popup: `src/entrypoints/popup/`
163+
- Extension background: `src/entrypoints/background.ts`
164+
165+
Extension build uses custom WXT module to:
166+
167+
- Extract inline scripts for CSP compliance
168+
- Chunk large dependencies (Prettier, highlight.js)
169+
- Handle virtual modules during development
170+
171+
## Working with Markdown Content
172+
173+
When modifying the editor or renderer:
174+
175+
1. Changes to editor update `posts[currentPostIndex].content`
176+
2. Content is auto-saved to localStorage via reactive watchers
177+
3. Call `editorRefresh()` to re-render preview
178+
4. Use `formatContent()` to run Prettier on Markdown
179+
5. Export functions: `exportEditorContent2MD()`, `exportEditorContent2HTML()`
180+
181+
## CSS Customization
182+
183+
The CSS editor (CodeMirror instance) allows users to override theme styles:
184+
185+
- Stored in `cssContentConfig.tabs`
186+
- Supports multiple schemes (tabs)
187+
- Auto-hints enabled for CSS properties
188+
- Format with `Shift-Alt-F`
189+
- Changes apply in real-time via `updateCss()`

0 commit comments

Comments
 (0)