fumadocs-article-importer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fumadocs Article Importer

Fumadocs 文章导入工具

Import external articles into a Fumadocs project with tri-language support (en, zh, fr), auto-classification, and proper MDX formatting.

将外部文章导入Fumadocs项目，支持三语言（英文、中文、法文）、自动分类以及标准MDX格式。

Prerequisites

前置条件

Fumadocs project initialized
Jina API Key configured (必需)
```
curl
```
installed for article fetch and image downloads
Write access to
```
content/docs/
```
and
```
public/images/
```

已初始化Fumadocs项目
已配置Jina API Key（必需）
已安装
```
curl
```
用于文章获取和图片下载
拥有
```
content/docs/
```
和
```
public/images/
```
目录的写入权限

Configuration

配置

Jina API Key 配置（必需）

Step 1: 获取 API Key

访问 https://jina.ai/reader
注册/登录账号
在 Dashboard 生成 API Key（格式：
```
jina_xxxxxxxxxxxx
```
）

Step 2: 配置到环境变量

编辑

~/.clawdbot/moltbot.json

：

json

{
  "env": {
    "JINA_API_KEY": "jina_你的API_KEY"
  }
}

或添加到

~/.openclaw/.env

：

bash

JINA_API_KEY=jina_你的API_KEY

Step 3: 验证配置

bash

undefined

步骤1：获取API Key

访问 https://jina.ai/reader
注册/登录账号
在控制台生成API Key（格式：
```
jina_xxxxxxxxxxxx
```
）

步骤2：配置到环境变量

编辑

~/.clawdbot/moltbot.json

：

json

{
  "env": {
    "JINA_API_KEY": "jina_你的API_KEY"
  }
}

或添加到

~/.openclaw/.env

：

bash

JINA_API_KEY=jina_你的API_KEY

步骤3：验证配置

bash

undefined

测试 API 可用性

curl -s "https://r.jina.ai/https://example.com"
-H "Authorization: Bearer $JINA_API_KEY" | head -20

undefined

curl -s "https://r.jina.ai/https://example.com"
-H "Authorization: Bearer $JINA_API_KEY" | head -20

undefined

Workflow

工作流程

Step 1: Get Article Info

步骤1：获取文章信息

Ask user:

Article URL
Target languages (default: en, zh, fr)
Image strategy (default: auto)

询问用户：

文章URL
目标语言（默认：英文、中文、法文）
图片策略（默认：自动）

Step 2: Fetch Article Content

步骤2：获取文章内容

使用 Jina Reader API（curl 方式）:

bash

undefined

使用Jina Reader API（curl方式）:

bash

undefined

获取文章内容（Markdown 格式）

获取文章内容（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**:

```bash

if [ ! -s /tmp/article.md ]; then echo "❌ 文章获取失败" exit 1 fi

echo "✅ 文章内容已获取" head -20 /tmp/article.md


**提取图片URL**:

```bash

从 Markdown 中提取所有图片 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} 张图片"


**尝试提取发布日期（可选）**:

```bash

IMAGE_COUNT=$(wc -l < /tmp/images.txt) echo "📊 发现 ${IMAGE_COUNT} 张图片"


**尝试提取发布日期（可选）**:

```bash

使用 Jina 的日期检测 API

使用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 "日期未找到"

undefined

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 "日期未找到"

undefined

Step 3: Generate Slug

步骤3：生成Slug

Create URL-friendly slug from title:

Lowercase, hyphens for spaces
Remove special characters
Example: "Building Agents with Skills" →
```
building-agents-with-skills
```

根据标题创建URL友好的Slug：

小写字母，用连字符替代空格
移除特殊字符
示例："Building Agents with Skills" →
```
building-agents-with-skills
```

Step 4: Process Images

步骤4：处理图片

图片下载和重命名（重要！）:

bash

undefined

图片下载和重命名（重要！）:

bash

undefined

创建图片目录

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（无连字符）

undefined

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（无连字符）

undefined

Step 5: Classify Article

步骤5：文章分类

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

将文章分类为以下8类之一（详见

references/classification-rules.md

）：

分类	描述
`development`	编码、API、框架
`ai-ml`	AI/ML主题、大语言模型
`tools`	开发者工具、CLI
`best-practices`	模式、方法论
`architecture`	系统设计、基础设施
`testing`	测试、质量保证
`security`	安全实践
`general`	其他所有内容

Step 6: Create MDX Files

步骤6：创建MDX文件

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

yaml

---
title: {translated_title}
description: {translated_description}
author: {original_author}
date: {publication_date}
lang: {en|zh|fr}
category: {category}
---

为每种语言创建MDX文件：

英文:

content/docs/en/{category}/{slug}.mdx

中文:

content/docs/zh/{category}/{slug}.mdx

法文:

content/docs/fr/{category}/{slug}.mdx

前置元数据模板（详见

assets/frontmatter-template.yaml

）：

yaml

---
title: {translated_title}
description: {translated_description}
author: {original_author}
date: {publication_date}
lang: {en|zh|fr}
category: {category}
---

Step 7: Translate Content

步骤7：翻译内容

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

使用article-translator功能进行翻译：

标题和描述
文章正文（保留代码块、MDX语法）
图片替代文本

关键规则:

代码块保持不变
保留MDX组件语法
在中文/韩文的
```
**粗体**
```
后添加空格

Step 8: Update Navigation

步骤8：更新导航

Update

content/docs/{lang}/meta.json

json

{
  "title": "{Category Title}",
  "pages": ["existing-page", "{new-slug}"]
}

See

references/meta-json-best-practices.md

for details.

更新

content/docs/{lang}/meta.json

：

json

{
  "title": "{Category Title}",
  "pages": ["existing-page", "{new-slug}"]
}

详情请见

references/meta-json-best-practices.md

。

Step 9: Generate Illustration (Optional)

步骤9：生成插图（可选）

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

使用philosophical-illustrator功能创建封面图片：

Generate an 800x450px SVG illustration for: {article_title}
Theme: {category}

保存至:

public/images/docs/{slug}/cover.svg

Step 10: Validate and Report

步骤10：验证与报告

Verify all files created correctly
Check MDX syntax compiles
Verify image paths resolve
Report summary to user

验证所有文件已正确创建
检查MDX语法可正常编译
验证图片路径可正确解析
向用户报告总结信息

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)

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`

错误	解决方案
未提取到图片	确认已启用 `withAllImages: true`
CORS失败	切换至下载策略
翻译失败	检查article-translator功能是否可用
Slug冲突	添加日期后缀： `{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

```
references/classification-rules.md
```
- 分类规则
```
references/fumadocs-components.md
```
- 可用MDX组件
```
references/meta-json-best-practices.md
```
- 导航配置
```
references/jina-mcp-setup.md
```
- Jina MCP配置
```
assets/frontmatter-template.yaml
```
- 前置元数据模板