flyanx/xiaohongshu-card

Xiaohongshu Card Generator (xiaohongshu-card)

Convert a popular science article → a complete set of Xiaohongshu image-text cards (multiple JPGs), executed according to battle-tested standards. Suitable for articles from WeChat Official Accounts, Sohu, journals, etc., adapted for Xiaohongshu.

1. Output Specifications (Fixed)

Item	Standard
Card size	1080 × 1440 (3:4, Xiaohongshu recommended ratio)
Export format	JPG quality 95, named semantically (01-cover.jpg, 02-five-step-overview.jpg…10-back-cover.jpg)
Deliverable	JPG only; HTML is only an internal working file (kept in the project directory for easy revision and re-export)
Mobile font size	Body text 29-30px / Title 60-92px / Step title 40px / Parameter values 46px / Captions 20px (at 1080 width, still clear when scaled down on mobile)

2. Page Structure (Fixed Template + Adaptive Step Count)

Cover → Overview → STEP pages (one per step, STEP 0N/total steps) → Pitfalls → FAQ → Back cover

• Cover: Centered text layout (tagline + subtitle + main title + subtitle2), designed with white space
• Overview: Three advantage blocks + one-sentence principle + five-step directory (STEP number + name + one-sentence summary)
• Step Page: Top red "STEP 0N / 05" badge + step name title + content blocks (key points/process list/parameter card) + original article image
• Pitfalls Page: Key reminders in large font (each line prefixed with ◆)
• FAQ Page: FAQ in large card format, about 4 items (if insufficient, may extract from other article paragraphs, but must not fabricate)
• Back Cover: FIN → Thank you for reading / Thank you for following → Brand logo → ＋ Follow → "Brand · More dry goods on the way" (content read from brand configuration)
• When step count ≠ 5, adapt automatically (total steps follow); if images/content are crowded, split pages (1-2 info blocks per page is most comfortable)

3. Image Strategy (Original Article Images Priority)

1. Original article images first: Fetch images from the original article, verify each image's position in the article to ensure one-to-one correspondence with the text (if not aligned, move the image to the appropriate page or inform the user)
2. Sohu AES decryption: Sohu article image data-src is AES-ECB-PKCS7 encrypted with key www.sohu.com6666. Use scripts/decrypt-sohu.py to decrypt to the real URL //qX.itc.cn/.... When downloading, include Referer (article page URL) + browser User-Agent to prevent hotlinking.
3. If the original article truly has no images: Only then may AI-generated schematic images be used as substitutes—white background, single color scheme (cross-style general), and must be explicitly labeled "AI-generated" to the user.
4. Horizontal screenshot images (e.g., 1080×289): Use fixed-height .fig container + object-fit: contain; stack multiple images vertically (.fig-col) or side-by-side (.fig-row).

4. Quality Verification (Mandatory, Must Do Before Delivery)

Use scripts/verify.js (Playwright) for programmatic checks; if not up to standard, automatically iterate to adjust font size, spacing, image height:

• Content page fill rate 80-100% (empty space ≤ 20%, pages must not be too sparse)
• No overflow (the bottommost content element ≤ card height)
• All images loaded successfully (naturalWidth > 0)
• Cover and back cover are designed with intentional white space, exempt from fill rate checks

5. Style System (3 Built-in, Default: Rational Experiment Manual)

Style	Visual	Use Case
A Rational Experiment Manual (default)	White background black text + red #E63946 accent, Swiss grid, numbered blocks, STEP badge	Professional dry goods, experimental operations
B Premium White Space	Off-white background + warm gold #D4A574, ultra-light font weight, generous white space	High-end, minimalistic scenarios
C Soft Science Popularization	Beige background #f6f2ea + natural green #7a8a72, rounded cards	Approachable science popularization accounts

Adding a new style: Add a style class (e.g., .X) in the template CSS and register it in the STYLES configuration.

6. Brand Configuration

assets/brand-config.example.json defines: brand name, logo path, back cover copy, default style. Default includes IGE Biotech configuration (logo: assets/logo-ige.png). For other brands, copy the file and modify the fields.

7. Red Lines (Violation = Rework)

• Remove platform-restricted/redundant information: Content source, like/follow CTAs, "swipe left" prompts, etc., must not appear
• Do not fabricate content: All information must come from the original article; supplementary information (e.g., FAQ) must be extracted from other paragraphs of the original article
• Images must correspond one-to-one with the text: Verify original article positions; if the original has no image, do not include one (fill with text layout) or label as AI-generated
• Anti-AI slop: No emoji decorations, no purple gradients, no rounded corners + left color borders, no fake SVG images, no system default fonts as display fonts

8. Workflow (9 Steps)

1. Fetch article: Use WebFetch/curl to get the full article (title, WeChat Official Account, date, body, images), save as raw HTML
2. Extract essence: Organize according to page structure—concepts/principles, steps (including parameters), notes, FAQ
3. Fetch images: Parse original article images (Sohu uses scripts/decrypt-sohu.py), download and record each image's position in the original article
4. Determine page structure: Cover/Overview/STEP N pages/Pitfalls/FAQ/Back cover, determine step count
5. Generate HTML: Copy assets/card-template.html, fill content into the PAGES data array in JS (see template comments), place images in the project's imgs/ directory
6. Verify and iterate: Open with Playwright → run scripts/verify.js → adjust font size/spacing/image height based on results until 10/10 PASS
7. Export JPG: Modify scripts/export-jpg.js's NAMES array → run export (1080×1440 quality 95)
8. User confirmation: Show all cards → tweak based on feedback (copy/color scheme/logo/back cover) → re-export
9. Deliver: List JPG files + publishing tips (title, hashtag suggestions)

9. Template Usage Guide (card-template.html)

• Single-file HTML + vanilla JS data-driven: The PAGES array contains one object per page, each with a blocks array containing content blocks
• Block types: {t, p} text block / {t, lines:[['a)','text'],...]} process list / {params:[[value, label],...]} parameter card / {step:{t,d}} step description / {img} {imgs, col} images / {faq} / {notes} / {dir} five-step directory / {why} advantage block / {tip} tip block / {recape} recap block
• Three page types: type:'cover' (cover), type:'step' (step page, step: N), type:'content' (overview/pitfalls/FAQ), type:'end' (back cover)

10. Environment Dependencies

• Node.js + Playwright (project-level npm i playwright)
• Python3 + pycryptodome (for Sohu decryption only)