Fumadocs Article Importer
Import external articles into a Fumadocs project with tri-language support (en, zh, fr), auto-classification, and proper MDX formatting.
Prerequisites
-
Fumadocs project initialized
-
Jina API Key configured (必需)
-
curl installed for article fetch and image downloads
-
Write access to content/docs/ and public/images/
Configuration
Jina API Key 配置（必需）
Step 1: 获取 API Key
-
注册/登录账号
-
在 Dashboard 生成 API Key（格式：jina_xxxxxxxxxxxx ）
Step 2: 配置到环境变量
编辑 ~/.clawdbot/moltbot.json ：
{ "env": { "JINA_API_KEY": "jina_你的API_KEY" } }
或添加到 ~/.openclaw/.env ：
JINA_API_KEY=jina_你的API_KEY
Step 3: 验证配置
测试 API 可用性
curl -s "https://r.jina.ai/https://example.com"
-H "Authorization: Bearer $JINA_API_KEY" | head -20
Workflow
Step 1: Get Article Info
Ask user:
-
Article URL
-
Target languages (default: en, zh, fr)
-
Image strategy (default: auto)
Step 2: Fetch Article Content
使用 Jina Reader API（curl 方式）:
获取文章内容（Markdown 格式）
curl -s "https://r.jina.ai/{article_url}"
-H "Authorization: Bearer ${JINA_API_KEY}"
-o /tmp/article.md
检查获取结果
if [ ! -s /tmp/article.md ]; then echo "❌ 文章获取失败" exit 1 fi
echo "✅ 文章内容已获取" head -20 /tmp/article.md
提取图片 URL:
从 Markdown 中提取所有图片 URL
grep -oE 'https://[^)]+.(png|jpg|jpeg|webp|gif)' /tmp/article.md > /tmp/images.txt
统计图片数量
IMAGE_COUNT=$(wc -l < /tmp/images.txt) echo "📊 发现 ${IMAGE_COUNT} 张图片"
尝试提取发布日期（可选）:
使用 Jina 的日期检测 API
curl -s "https://r.jina.ai/{article_url}"
-H "Authorization: Bearer ${JINA_API_KEY}"
-H "X-With-Generated-Summary: true"
| grep -oE 'Published:.|Updated:.' || echo "日期未找到"
Step 3: Generate Slug
Create URL-friendly slug from title:
-
Lowercase, hyphens for spaces
-
Remove special characters
-
Example: "Building Agents with Skills" → building-agents-with-skills
Step 4: Process Images
图片下载和重命名（重要！）:
创建图片目录
mkdir -p public/images/docs/{slug}
下载图片（使用安全的文件名）
i=1 while IFS= read -r img_url; do
使用 img01.png, img02.png 格式（避免连字符+数字）
printf -v filename "img%02d.png" $i
echo "下载: $img_url → $filename" curl -s -o "public/images/docs/{slug}/$filename" "$img_url"
更新 Markdown 中的图片引用
sed -i "s|$img_url|/images/docs/{slug}/$filename|g" /tmp/article.md
((i++)) done < /tmp/images.txt
echo "✅ 已下载 $((i-1)) 张图片"
图片文件名规则（重要！）:
❌ 错误：img-1.png, img-10.png（MDX 会解析 -1, -10 为表达式） ✅ 正确：img01.png, img10.png, openclaw01.png（无连字符）
Step 5: Classify Article
Classify into one of 8 categories (see references/classification-rules.md ):
Category Description
development
Coding, APIs, frameworks
ai-ml
AI/ML topics, LLMs
tools
Developer tools, CLIs
best-practices
Patterns, methodologies
architecture
System design, infrastructure
testing
Testing, QA
security
Security practices
general
Everything else
Step 6: Create MDX Files
For each language, create MDX file:
English: content/docs/en/{category}/{slug}.mdx
Chinese: content/docs/zh/{category}/{slug}.mdx
French: content/docs/fr/{category}/{slug}.mdx
Frontmatter template (see assets/frontmatter-template.yaml ):
title: {translated_title} description: {translated_description} author: {original_author} date: {publication_date} lang: {en|zh|fr} category: {category}
Step 7: Translate Content
Use article-translator skill to translate:
-
Title and description
-
Article body (preserving code blocks, MDX syntax)
-
Image alt text
Key rules:
-
Keep code blocks unchanged
-
Preserve MDX component syntax
-
Add space after bold in Chinese/Korean
Step 8: Update Navigation
Update content/docs/{lang}/meta.json :
{ "title": "{Category Title}", "pages": ["existing-page", "{new-slug}"] }
See references/meta-json-best-practices.md for details.
Step 9: Generate Illustration (Optional)
Use philosophical-illustrator skill to create cover image:
Generate an 800x450px SVG illustration for: {article_title} Theme: {category}
Save to: public/images/docs/{slug}/cover.svg
Step 10: Validate and Report
-
Verify all files created correctly
-
Check MDX syntax compiles
-
Verify image paths resolve
-
Report summary to user
Output Structure
content/docs/ ├── en/{category}/{slug}.mdx ├── zh/{category}/{slug}.mdx └── fr/{category}/{slug}.mdx
public/images/docs/{slug}/ ├── image1.png ├── image2.png └── cover.svg (optional)
Error Handling
Error Solution
No images extracted Verify withAllImages: true was used
CORS failure Switch to download strategy
Translation failed Check article-translator skill is available
Slug conflict Append date suffix: {slug}-2024-01-15
References
-
references/classification-rules.md
-
Category classification rules
-
references/fumadocs-components.md
-
Available MDX components
-
references/meta-json-best-practices.md
-
Navigation configuration
-
references/jina-mcp-setup.md
-
Jina MCP configuration
-
assets/frontmatter-template.yaml
-
Frontmatter template