jiabai Article Diagram
Automatically generate professional SVG illustrations for Markdown articles, reducing cognitive load for junior engineers and product managers.
Workflow
Article Input → Extract Know-how → Design Illustration List → Generate SVG
→ Validate Syntax → Coverage Check → Merge to Markdown
↓
S-tier Content
Generate Bilingual Illustration Page
(Optional) Export JPEG
1. Analyze Article Structure
Read Markdown, extract heading hierarchy, paragraph content, code blocks, and existing images.
2. Extract Know-how List (Critical Step)
Before generating illustrations, extract know-how points from the article:
- Read through the article, list all know-how/methodologies/best practices
- For each know-how, determine:
- Does it need visualization?
- What type of diagram is appropriate?
- Form an illustration list, ensure complete coverage
Example:
Article: "Building a C compiler with parallel Claudes"
Know-how List:
1. Harness loop mechanism → Architecture diagram ✅
2. Task lock synchronization → Flowchart ✅
3. GCC Oracle parallelization strategy → Flowchart ✅ (Critical know-how!)
4. Test Harness design principles → Comparison diagram ✅
5. Context pollution issue → Comparison diagram ✅
6. Time blindness issue → Comparison diagram ✅
7. Project results statistics → Stats diagram ✅
3. Identify Illustration Positions
Use LLM to analyze the article and identify positions needing visualization. Criteria:
- Flowchart: ≥3 sequential steps
- Architecture diagram: ≥3 component relationships
- Sequence diagram: Interactions with temporal order
- Comparison diagram: Two or more approaches comparison
Constraints: 3-6 illustrations per article, 3-8 components per diagram.
4. Generate SVG
See references/design-spec.md for design specifications.
Core Principles:
- Dark background (#0B0F19)
- Unified CSS class styles
- Components use card + title + description
- Different types use different colors
Diagram Types:
| Type | Purpose | Recommended Size |
|---|---|---|
| flowchart | Process steps | 900×400 |
| architecture | System architecture | 1100×600 |
| sequence | Sequential interactions | 1000×500 |
| comparison | Approach comparison | 900×340 |
Generation Helper:
Use Python functions from scripts/generate_diagram.py to assist in generating standard SVG:
from generate_diagram import ColorScheme, card, step_circle, arrow_marker, connection_line, svg_template
5. Validate SVG
Must validate:
# Python validation script (recommended)
python scripts/validate_svg.py file.svg
# Linux/macOS/Git Bash - Check unescaped &
grep -E '&[^a]' file.svg | grep -v '&' | grep -v '<' | grep -v '>'
# Windows PowerShell
Select-String -Path "file.svg" -Pattern '&[^a]' | Where-Object { $_.Line -notmatch '&|<|>' }
Common Errors:
&→&<(in text) →<>(in text) →>
6. Coverage Check (Critical Step)
After generating illustrations, must perform coverage check:
- Review know-how list
- Check if each know-how has corresponding illustration
- Add illustrations for missing know-how
Checklist:
☐ Architecture overview has diagram?
☐ Key processes have diagrams?
☐ Know-how methodologies have diagrams?
☐ Comparisons/decision points have diagrams?
☐ Data/statistics have diagrams?
7. Merge to Markdown
Insert after relevant paragraphs:
8. Export JPEG (Optional)
To convert SVG to JPEG format (for platforms that don't support SVG):
# Convert all SVGs in directory
node scripts/svg-to-jpeg.js ./diagrams
# Convert single file
node scripts/svg-to-jpeg.js ./diagrams/chart.svg
# Specify output directory and quality
node scripts/svg-to-jpeg.js ./diagrams ./output --quality 95 --bg #FFFFFF
Parameters:
| Parameter | Description | Default |
|---|---|---|
--quality |
JPEG quality (1-100) | 90 |
--bg |
Background color (hex) | #FFFFFF |
9. Generate Bilingual Illustration Page (S-tier Content)
When processing S-tier content, must generate standalone bilingual illustration pages.
HTML Structure Requirements
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Article Title</title>
<style>/* Responsive styles */</style>
</head>
<body>
<section>
<h2>Diagram Title</h2>
<div class="diagram">
<!-- Must embed complete SVG code -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 550">
<defs>...</defs>
<!-- Complete SVG content -->
</svg>
<div class="diagram-caption">Figure 1: Description</div>
</div>
</section>
</body>
</html>
SVG Embedding Specification (Critical)
Must embed complete SVG code, no placeholders:
<!-- ✅ Correct -->
<div class="diagram">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 550">
<defs>
<style>.bg { fill: #0B0F19; }</style>
<marker id="arrowhead" .../>
</defs>
<rect class="bg" width="1100" height="550"/>
<text x="550" y="40">Title</text>
<!-- All graphic elements -->
</svg>
</div>
<!-- ❌ Wrong: placeholder -->
<div class="diagram">
<svg>📊 Please see standalone SVG file</svg>
</div>
Validation Checklist
- SVG fully embedded (not placeholder)
- Contains
<defs>and all style definitions - Contains
<marker>and other reference elements - All graphic elements complete
- HTML file size >10KB (including SVG)
- Mobile responsive (viewport meta tag)
- SVG uses
max-width: 100%; height: auto;
Example
Input: Generate illustrations for sources/article.md
Steps:
1. Extract know-how list: 7 key points
2. Design illustration list: 4 diagrams
3. Generate SVG...
4. Coverage check: Missing GCC Oracle strategy, add
5. Final output: 5 illustrations
Output:
✓ Analyzed article: Identified 7 know-how points
✓ Designed list: 5 illustrations
✓ Generated diagrams/arch-1.svg (Architecture diagram)
✓ Generated diagrams/flow-2.svg (Flowchart)
✓ Generated diagrams/flow-3.svg (GCC Oracle strategy)
✓ Generated diagrams/comp-4.svg (Design principles comparison)
✓ Generated diagrams/stats-5.svg (Statistics diagram)
✓ SVG syntax validation passed
✓ Coverage check passed
✓ Merged to article.md
Resources
references/
design-spec.md- Detailed design specifications (color system, typography, component templates)
scripts/
generate_diagram.py- Python SVG generation helper scriptvalidate_svg.py- SVG syntax validation script (recommended)svg-to-jpeg.js- SVG to JPEG conversion script (requires Node.js)