@feex/cli

Markdown 文档解析和转换 CLI 工具

命令

• feex init docs：创建文档项目

• feex parser json： 将 Markdown 文件解析为 JSON 数据（元数据 + HTML 内容）

• feex parser html： 把md解析成可直接打开的html

• feex upload： 把解析的产物上传到oss上

• feex --help： 帮助

• json

  • list.json

• html

  • list.html
  • detail
    • xxxxx.html

功能特性

• 📝 解析 Markdown：将 Markdown 文件解析为 JSON 数据（元数据 + HTML 内容）
• 🎨 生成 HTML：基于解析的 JSON 数据生成精美的详情页 HTML
• ☁️ 多云上传：支持腾讯云 COS、阿里云 OSS、七牛云 Kodo
• 🔧 灵活配置：通过 feex.config.js 配置所有选项
• 📂 目录结构：保持源文件目录结构不变

安装

# 在 workspace 中安装
pnpm add @feexcode/cli -D -w

快速开始

1. 创建配置文件

在项目根目录创建 feex.config.js：

export default {
  // 上传配置
  upload: {
    provider: "cos", // cos | oss | qiniu

    cos: {
      secretId: "your-secret-id",
      secretKey: "your-secret-key",
      bucket: "your-bucket",
      region: "ap-beijing",
    },

    prefix: "", // 上传路径前缀，空字符串表示根目录
    distDir: "dist",
  },

  // 解析配置
  parse: {
    srcDir: "src",
    distDir: "dist",
  },
};

2. 添加脚本到 package.json

{
  "scripts": {
    "parse": "feex parse",
    "html": "feex html --all",
    "upload": "feex upload",
    "deploy": "pnpm parse && pnpm html && pnpm upload"
  }
}

3. 使用命令

# 解析所有 Markdown 文件
pnpm parse

# 生成所有 HTML 页面
pnpm html

# 上传到云存储
pnpm upload

# 一键部署（解析 + 生成 HTML + 上传）
pnpm deploy

命令详解

feex parse - 解析 Markdown

将 Markdown 文件解析为 JSON 数据：

# 解析所有文件
feex parse

# 解析指定文件（增量更新）
feex parse src/javascript/closure.md
feex parse src/javascript/closure.md src/react/hooks.md

输出结构：

dist/
├── problems/              # 问题详情（保持源文件目录结构）
│   ├── javascript/
│   │   ├── closure.json
│   │   └── promise.json
│   └── react/
│       └── hooks.json
├── list.json             # 问题列表（不含 HTML 内容）
└── categories.json       # 分类索引

JSON 数据格式：

{
  "meta": {
    "id": "javascript/closure",
    "title": "JavaScript 闭包详解",
    "category": "JavaScript",
    "difficulty": "medium",
    "tags": ["闭包", "作用域"],
    "author": "张三",
    "createTime": "2024-01-15T00:00:00.000Z",
    "updateTime": "2024-01-20T00:00:00.000Z",
    "url": "/interview/javascript/closure",
    "filePath": "javascript/closure.md"
  },
  "content": "<h1>JavaScript 闭包详解</h1>..."
}

feex html - 生成 HTML

基于解析的 JSON 数据生成精美的详情页 HTML：

# 生成单个页面
feex html javascript/closure
feex html javascript/closure output/detail.html

# 生成所有页面
feex html --all

输出结构：

dist/
└── html/                 # HTML 页面（保持目录结构）
    ├── javascript/
    │   ├── closure.html
    │   └── promise.html
    └── react/
        └── hooks.html

HTML 特性：

• 🎨 精美的渐变头部设计
• 📊 元数据展示（分类、难度、标签等）
• 💎 完整的 Shiki 代码高亮
• 📱 响应式设计，支持移动端
• 🎯 自定义容器样式（tip、warning、danger、info）

feex upload - 上传到云存储

将生成的文件上传到云存储：

# 使用默认配置上传
feex upload

# 使用指定配置文件
feex upload -c custom.config.js

配置详解

上传配置

腾讯云 COS

export default {
  upload: {
    provider: "cos",
    cos: {
      secretId: "your-secret-id",
      secretKey: "your-secret-key",
      bucket: "your-bucket-appid",
      region: "ap-beijing", // ap-guangzhou, ap-shanghai
    },
    prefix: "", // 上传路径前缀
    distDir: "dist",
  },
};

阿里云 OSS

export default {
  upload: {
    provider: "oss",
    oss: {
      accessKeyId: "your-access-key-id",
      accessKeySecret: "your-access-key-secret",
      bucket: "your-bucket",
      region: "oss-cn-hangzhou", // oss-cn-beijing, oss-cn-shanghai
    },
    prefix: "",
    distDir: "dist",
  },
};

七牛云 Kodo

export default {
  upload: {
    provider: "qiniu",
    qiniu: {
      accessKey: "your-access-key",
      secretKey: "your-secret-key",
      bucket: "your-bucket",
      zone: "Zone_z2", // Zone_z0(华东), Zone_z1(华北), Zone_z2(华南)
      domain: "your-cdn-domain.com", // CDN 加速域名
    },
    prefix: "",
    distDir: "dist",
  },
};

Markdown Frontmatter

在 Markdown 文件头部添加元数据：

---
title: JavaScript 闭包详解
category: JavaScript
difficulty: medium
tags: [闭包, 作用域, 函数式编程]
author: 张三
createTime: 2024-01-15
updateTime: 2024-01-20
estimatedTime: 15分钟
---

# JavaScript 闭包详解

你的内容...

支持的字段：

• title: 标题（默认：未命名）
• category: 分类（默认：未分类）
• difficulty: 难度（easy | medium | hard，默认：medium）
• tags: 标签数组
• author: 作者（默认：未知）
• createTime: 创建时间
• updateTime: 更新时间
• estimatedTime: 预计阅读时间

注意： 不需要设置 id 字段，系统会自动根据文件路径生成 ID（如 javascript/closure）

完整工作流

# 1. 编写 Markdown 文件
# src/javascript/closure.md

# 2. 解析 Markdown 为 JSON
pnpm parse
# 生成: dist/problems/javascript/closure.json

# 3. 生成 HTML 详情页
pnpm html
# 生成: dist/html/javascript/closure.html

# 4. 上传到云存储
pnpm upload
# 上传所有文件到配置的云存储

# 或者一键部署
pnpm deploy

目录结构示例

你的项目/
├── src/                          # Markdown 源文件
│   ├── javascript/
│   │   ├── closure.md
│   │   └── promise.md
│   └── react/
│       └── hooks.md
├── dist/                         # 生成的文件
│   ├── problems/                # JSON 数据（保持目录结构）
│   │   ├── javascript/
│   │   │   ├── closure.json
│   │   │   └── promise.json
│   │   └── react/
│   │       └── hooks.json
│   ├── html/                    # HTML 页面（保持目录结构）
│   │   ├── javascript/
│   │   │   ├── closure.html
│   │   │   └── promise.html
│   │   └── react/
│   │       └── hooks.html
│   ├── list.json               # 问题列表
│   └── categories.json         # 分类索引
├── feex.config.js              # CLI 配置文件
└── package.json

环境变量管理

如果不想在配置文件中硬编码敏感信息，可以：

方式 1：使用独立的环境变量模块

// env.local.js (加入 .gitignore)
export default {
  cos: {
    secretId: 'your-secret-id',
    secretKey: 'your-secret-key',
    bucket: 'your-bucket',
    region: 'ap-beijing',
  }
}

// feex.config.js
import env from './env.local.js'

export default {
  upload: {
    provider: 'cos',
    cos: env.cos,
    prefix: '',
    distDir: 'dist',
  }
}

方式 2：使用 dotenv（如果项目已使用）

// 在 feex.config.js 顶部
import "dotenv/config";

export default {
  upload: {
    provider: "cos",
    cos: {
      secretId: process.env.COS_SECRET_ID,
      secretKey: process.env.COS_SECRET_KEY,
      bucket: process.env.COS_BUCKET,
      region: process.env.COS_REGION,
    },
  },
};

常见问题

Q: 如何只上传 JSON 而不上传 HTML？

在配置文件中设置 distDir 为 dist（不包含 html 子目录），HTML 在单独的 dist/html/ 中不会被上传。

Q: 如何修改上传路径？

修改配置文件中的 prefix 字段：

• 空字符串 ''：上传到根目录
• 'docs'：上传到 docs/ 目录
• 'interview/problems'：上传到 interview/problems/ 目录

License

MIT