mdx-article-publisher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MDX Article Publisher

MDX 文章发布工具

通用 MDX 文档发布工具 - 适用于任何 MDX 项目（Fumadocs、Next.js、Docusaurus 等）。

通用MDX文档发布工具 - 适用于所有MDX项目（Fumadocs、Next.js、Docusaurus等）。

Prerequisites

前置要求

Git repository with MDX files
Python 3.x (for validation script)
Write access to content directories
Git credentials configured

包含MDX文件的Git仓库
Python 3.x（用于验证脚本）
内容目录的写入权限
已配置Git凭证

支持的项目类型

项目类型	Build 命令	状态
Fumadocs	`pnpm build:docs`	✅ 已测试
Next.js + MDX	`npm run build`	✅ 兼容
Docusaurus	`npm run build`	✅ 兼容
通用 MDX	自定义	✅ 可配置

项目类型	Build命令	状态
Fumadocs	`pnpm build:docs`	✅ 已测试
Next.js + MDX	`npm run build`	✅ 兼容
Docusaurus	`npm run build`	✅ 兼容
通用MDX	自定义	✅ 可配置

Workflow

工作流

Step 0: 配置 Build 命令（首次使用）

步骤0：配置Build命令（首次使用）

Fumadocs / shiptiny:

bash

undefined

Fumadocs / shiptiny:

bash

undefined

pnpm monorepo

pnpm build:docs


**Next.js**:
```bash
npm run build

自定义:

bash

undefined

pnpm build:docs


**Next.js**:
```bash
npm run build

自定义:

bash

undefined

在 skill 执行时询问用户

工具执行时将询问用户

undefined

undefined

Step 1: Identify Target Files

步骤1：确定目标文件

Single article:

bash

content/docs/en/ai-ml/my-article.mdx

Multiple articles:

bash

content/docs/en/ai-ml/

The skill will detect:

New MDX files
Modified MDX files
Multi-language versions (en, zh, fr)

单篇文章:

bash

content/docs/en/ai-ml/my-article.mdx

多篇文章:

bash

content/docs/en/ai-ml/

该工具会检测：

新增的MDX文件
修改的MDX文件
多语言版本（en、zh、fr）

Step 2: Check Git Status

步骤2：检查Git状态

bash

git status
git diff --staged

bash

git status
git diff --staged

Step 3: Run Validation

步骤3：执行验证

3.1 MDX Syntax Validation

3.1 MDX语法验证

bash

python scripts/validate_mdx.py /path/to/article.mdx

bash

python scripts/validate_mdx.py /path/to/article.mdx

Or directory:

或目录:

python scripts/validate_mdx.py content/docs/en/ai-ml/


**What it checks**:
- ✅ YAML frontmatter (title, description, lang)
- ✅ Unescaped operators (`>` → `&gt;`, `<` → `&lt;`)
- ✅ MDX component tag balance
- ✅ Common syntax errors

python scripts/validate_mdx.py content/docs/en/ai-ml/


**验证内容包括**:
- ✅ YAML前置元数据（title、description、lang）
- ✅ 未转义的运算符（`>` → `&gt;`，`<` → `&lt;`）
- ✅ MDX组件标签闭合
- ✅ 常见语法错误

3.2 Build Validation (Recommended)

3.2 构建验证（推荐）

bash

undefined

bash

undefined

For Fumadocs/Next.js

适用于Fumadocs/Next.js

pnpm build:docs

Or generic

或通用命令

npm run build


Build catches all MDX syntax errors that validation script may miss.

npm run build


构建可以捕获验证脚本可能遗漏的所有MDX语法错误。

Step 4: Review Validation Results

步骤4：查看验证结果

Example output:

❌ ERRORS (2):
  File: content/docs/en/ai-ml/article.mdx:730
  Error: Unescaped operator. Use &gt; instead of > in: >80% accuracy

⚠️  WARNINGS (1):
  Warning: Lang code "ko" may not be supported.

📊 SUMMARY:
  Files valid: 0
  Errors: 2

Fix errors:

Replace
```
>
```
with
```
&gt;
```
,
```
<
```
with
```
&lt;
```
Add missing frontmatter fields
Close unclosed MDX components

示例输出:

❌ 错误（2）:
  文件: content/docs/en/ai-ml/article.mdx:730
  错误: 存在未转义的运算符。请将文本中的>替换为&gt;，例如>80% accuracy改为&gt;80% accuracy

⚠️ 警告（1）:
  警告: 语言代码"ko"可能不受支持。

📊 摘要:
  验证通过的文件: 0
  错误数: 2

修复错误:

将
```
>
```
替换为
```
&gt;
```
，
```
<
```
替换为
```
&lt;
```
补充缺失的前置元数据字段
闭合未关闭的MDX组件标签

Step 5: Create Semantic Commit

步骤5：创建语义化提交

Commit message format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

```
feat
```
: New article
```
fix
```
: Article fix
```
docs
```
: Documentation update
```
refactor
```
: Major rewrite
```
translate
```
: Translation update

Examples:

bash

undefined

提交信息格式:

<类型>(<范围>): <描述>

[可选正文]

[可选页脚]

提交类型:

```
feat
```
: 新增文章
```
fix
```
: 修复文章问题
```
docs
```
: 更新文档
```
refactor
```
: 大幅重写
```
translate
```
: 更新翻译

示例:

bash

undefined

New article

新增文章

git commit -m "feat(ai-ml): add jina-vlm article"

git commit -m "feat(ai-ml): 添加jina-vlm文章"

Multiple articles

多篇文章

git commit -m "feat(ai-ml): add 3 AI articles

jina-vlm: vision language model
rag-guide: RAG implementation
embedding-basics: embedding intro

skill-analysis: jina-vlm, rag-guide"

git commit -m "feat(ai-ml): 添加3篇AI文章

jina-vlm: 视觉语言模型
rag-guide: RAG实现指南
embedding-basics: 嵌入技术入门

工具分析: jina-vlm, rag-guide"

Translation

翻译更新

git commit -m "translate(zh): update jina-vlm to Chinese"

undefined

git commit -m "translate(zh): 将jina-vlm文章更新为中文"

undefined

Step 6: Push to Remote

步骤6：推送到远程仓库

bash

git push origin main

With verification:

bash

undefined

bash

git push origin main

带验证的推送:

bash

undefined

Pull first to avoid conflicts

先拉取以避免冲突

git pull --rebase origin main

Then push

再推送

git push origin main

undefined

git push origin main

undefined

Validation Rules

验证规则

Required Frontmatter

必填前置元数据

yaml

---
title: Article Title
description: Brief description (1-2 sentences)
lang: en  # or zh, fr
---

yaml

---
title: 文章标题
description: 简短描述（1-2句话）
lang: en  # 或zh、fr
---

Common Errors

常见错误

Error	Cause	Fix
Unescaped operator	`>80%` in text	Use `>80%`
Missing lang	No `lang` field	Add `lang: en`
Unclosed tag	`<Callout>` without `</Callout>`	Close all tags

错误	原因	修复方案
未转义的运算符	文本中存在 `>80%`	使用 `>80%` 替代
缺失lang字段	未设置 `lang` 字段	添加 `lang: en`
标签未闭合	`<Callout>` 未搭配 `</Callout>`	闭合所有标签

Commit Type Detection

提交类型自动检测

File Pattern	Type	Example
New file	`feat`	`feat(ai-ml): add new article`
Modified	`docs`	`docs(ai-ml): update article`
zh/ directory	`translate`	`translate(zh): add Chinese version`

文件模式	类型	示例
新增文件	`feat`	`feat(ai-ml): 添加新文章`
修改文件	`docs`	`docs(ai-ml): 更新文章内容`
zh/目录下的文件	`translate`	`translate(zh): 添加中文版本`

Integration with Other Skills

与其他工具集成

Workflow:

fumadocs-article-importer
        ↓
skill-article-writer (optional)
        ↓
skill-article-publisher ← You are here

工作流:

fumadocs-article-importer
        ↓
skill-article-writer（可选）
        ↓
skill-article-publisher ← 当前工具

Troubleshooting

故障排除

Issue	Solution
Build fails	Check MDX syntax, run validation first
Git push rejected	`git pull --rebase` , then retry
Validation timeout	Large project - use `--no-build` flag

问题	解决方案
构建失败	检查MDX语法，先执行验证
Git推送被拒绝	执行 `git pull --rebase` 后重试
验证超时	针对大型项目，使用 `--no-build` 参数

Scripts

脚本说明

```
scripts/validate_mdx.py
```
- MDX syntax validation
```
scripts/publish_article.py
```
- Automated publish workflow

```
scripts/validate_mdx.py
```
- MDX语法验证脚本
```
scripts/publish_article.py
```
- 自动化发布工作流脚本

References

参考资料

```
references/semantic-commit-guide.md
```
- Commit message conventions

```
references/semantic-commit-guide.md
```
- 提交信息规范指南