md2wexin 1.0.0

package/README.md

@@ -0,0 +1,203 @@
+# md2weixin
+
+Markdown 转微信公众号文章工具：把 markdown 渲染为**主题化、全内联样式**的公众号 HTML，粘贴即用。
+
+支持两种方式：
+- **Web 在线转换**（推荐）：浏览器可视化编辑，实时预览、拖入图片自动内嵌、一键复制，产物可静态部署到 EdgeOne Pages；
+- **CLI 转换**：`npm install -g md2weixin` 后全局 `md2weixin` 命令（Node 单文件产物，任意目录可用），适合批量与脚本化；仓库内亦可用 `bun index.ts` 开发调试。
+
+## 特性
+
+- 内置 13 套主题（参考 `samples/主题.txt`）：赤陶橙、中国红、科技蓝、暖阳橙、古铜金、青草绿、典雅紫、柔和粉、翡翠绿、春、夏、秋、冬
+- **深浅两套配色**：每套主题都可用 `--mode dark` 得到反转配色的深色版（文字提亮、底色压暗、卡片描边）
+- **纸张色可配置**：`--paper '#FBF7EA'` 等护眼底色；主题亦可内置默认纸张色
+- 主题色自动派生：仅需一个主色，深浅变体、边框、表格、分割线、主色底上的文字（自动黑/白）全部自动计算
+- 覆盖公众号常用语法：标题、段落、粗体/斜体/删除线、行内代码、深色代码卡片、列表、图片、引用（含嵌套）、表格、分割线、链接
+- 额外支持：`==高亮==`、`$$` 块级公式（`--math katex` 可切 KaTeX 真实渲染）、Mermaid 占位提示
+- 图片处理：`--embed-images` 把 markdown 中的本地图片自动内嵌为 base64，远程 URL 原样保留
+- 实用 CLI：`--copy` 一键复制正文到剪贴板；输入目录时批量转换目录下所有 `.md`
+- 输出与 `samples/smaple.html`（青草绿主题·浅色）同风格，便于粘贴到微信编辑器
+
+![](./image.png)
+
+## 环境
+
+- [Node.js](https://nodejs.org) >= 18：`md2weixin` 全局命令的运行环境（发布的 npm 包为纯 Node 单文件产物，不依赖 Bun）
+- [Bun](https://bun.sh)：本仓库开发/构建工具（`bun install`、`bun run build:cli` 打包 CLI 产物）
+
+## Web 版（可视化转换）
+
+```sh
+# 本地开发（热更新）→ http://localhost:4443
+bun run dev
+
+# 构建静态产物到 output/
+bun run build
+```
+
+页面提供：Markdown 输入（可导入/拖入 `.md`）、13 主题与深浅配色/纸张色/字号/段间距/公式模式控制、
+公众号效果实时预览，以及「复制正文 HTML」「下载 HTML」。
+**本地图片**：把 md 中引用的图片拖入图片区（或随 md 一起导入、Ctrl+V 粘贴），渲染时按文件名自动内嵌为 base64。
+
+渲染全部在浏览器本地完成，无服务端依赖，`output/` 是纯静态目录，可直接部署。
+
+## 部署到 EdgeOne Pages
+
+`output/` 为纯静态站点产物，可用 EdgeOne Makers（原 EdgeOne Pages）部署。
+
+**CNB 自动部署**（仓库已内置 `.cnb.yml`）：推送到 main 分支后自动执行
+`bun run build` 并用 `npx edgeone makers deploy ./output -n wxgzh -t $EDGEONE_API_TOKEN`
+（token 由 `wuxia/secret` 仓库的 `edgone.env.yml` 注入，可在 EdgeOne 控制台生成 API Token 后配置）。
+
+**手动部署**：
+
+```sh
+bun install
+bun run build          # 产出 output/ 静态目录
+npx edgeone makers deploy ./output -n wxgzh -t $EDGEONE_API_TOKEN
+```
+
+> `edgeone makers` 为官方 CLI（原 `edgeone pages` 的升级命名空间），子命令等价。
+> 部署前请确认 EdgeOne 控制台已配置 API Token，或本地执行 `edgeone login`。
+
+## CLI 使用
+
+### 全局安装（推荐）
+
+发布到 npm registry 后安装，`md2weixin` 命令自动进入 PATH，任意目录可用：
+
+```sh
+# CNB 私有源：npm install -g md2weixin --registry https://npm.cnb.cool/wuxia/npm/
+npm install -g md2weixin
+
+# 列出所有主题
+md2weixin --list-themes
+
+# 基本转换（默认主题 青草绿·浅色，输出到源 md 同级的 <输入名>.html）
+md2weixin samples/sample.md
+
+# 指定主题与深色配色
+md2weixin samples/sample.md -t 科技蓝 --mode dark -o my-article.html
+
+# 护眼纸色 + 本地图片内嵌 + KaTeX 公式 + 一键复制
+md2weixin article.md --paper '#FBF7EA' --embed-images --math katex --copy
+
+# 自定义字号与段间距
+md2weixin samples/sample.md --theme 暖阳橙 --font-size 14 --paragraph-margin 0.8em
+
+# 批量转换目录下所有 markdown（各文件输出到自身同级目录）
+md2weixin samples/
+
+# 查看帮助
+md2weixin --help
+```
+
+> 安装包只包含单文件 Node 产物 `dist/index.js`（`package.json` 的 `bin` 指向它，由 `bun run build:cli` 从源码打包），运行时仅需 Node >= 18，无需 Bun。
+
+### 仓库内开发（源码直接运行）
+
+```sh
+bun install                                     # 安装依赖
+bun index.ts samples/sample.md -t 中国红        # 直接跑 TS 源码
+bun run convert -- samples/sample.md -t 中国红  # 通过 package.json 脚本
+```
+
+生成后浏览器打开 HTML 预览，全选复制 `<section>` 内容粘贴到公众号编辑器即可。
+
+## npm 发布
+
+CLI 以 npm 包发布，仓库已内置 CNB 私有源自动化（`.cnb.yml` 的 `$` 段）：
+
+- **手动触发**：`web_trigger_publish_npm` → 自动 `npm version` 更新版本号 → `bun run build:cli` 构建产物 → `npm publish` 到 `https://npm.cnb.cool/wuxia/npm/-/packages/`
+- **打 tag 推送**：`tag_push` → 用 tag 作为版本号发布，流程同上
+- 发布的包只包含 `dist/index.js` + `package.json` + `README.md`（见 `package.json` 的 `files` 白名单），版本号由流水线覆盖
+
+手动发布到任意源：
+
+```sh
+bun run build:cli      # 产出 dist/index.js（npm pack / publish 前置检查会校验）
+npm pack               # 本地试打包，可解压查看包内容
+npm publish            # prepublishOnly 校验 dist 存在后上传
+```
+
+安装验证：
+
+```sh
+npm install -g md2weixin   # 或 npm install -g ./md2wexin-1.0.0.tgz 本地验证
+md2weixin --help
+```
+
+## 命令参数
+
+| 参数 | 说明 | 默认 |
+| --- | --- | --- |
+| `<input.md 或目录>` | 输入 markdown 文件或目录（必填） | - |
+| `-t, --theme <name>` | 主题名称 | `青草绿` |
+| `--mode <light\|dark>` | 配色模式 | `light` |
+| `--paper <color>` | 正文纸张色，如 `#FBF7EA` | 白色 |
+| `-o, --output <path>` | 输出 HTML 文件（批量时忽略） | `<输入名>.html`（源 md 同级目录） |
+| `--font-size <px>` | 正文字号 | `16` |
+| `--paragraph-margin <em>` | 段间距 | `1em` |
+| `--math <plain\|katex>` | 公式模式：排版卡片 / KaTeX 真实渲染 | `plain` |
+| `--embed-images` | 本地图片转 base64 内嵌 | 关 |
+| `--copy` | 转换后复制正文到剪贴板 | 关 |
+| `-l, --list-themes` | 列出所有主题 | - |
+| `-h, --help` | 帮助 | - |
+
+## 项目结构
+
+```
+src/
+  themes.ts   # 主题定义 + light/dark 双配色派生（darken/lighten/mix/alpha/YIQ 亮度）
+  render.ts   # 预处理（代码块/公式/高亮占位）+ marked lexer + 自研递归渲染 + KaTeX
+  images.ts   # 本地图片 base64 内嵌（CLI，Node API）
+  cli.ts      # 命令行入口（参数解析、批量、剪贴板，Node API）
+web/
+  index.html  # Web 版页面（输入 / 样式控制 / 预览 三栏）
+  app.ts      # Web 端主逻辑（主题/图片/复制/下载）
+  embed.ts    # 浏览器端本地图片 base64 内嵌（按上传文件名匹配）
+  dev.ts      # 本地开发服务（Bun HTML import 热更新）
+  copy-assets.ts # 构建后把示例资源复制进 output/
+scripts/
+  build.ts    # CLI 打包：bun build → 单文件 Node 产物 dist/index.js
+  check-dist.mjs # npm publish 前置校验（纯 Node）
+index.ts      # CLI 入口（Bun 开发 / 打包入口）
+output/       # Web 构建产物（静态，可部署 EdgeOne Pages）
+dist/         # CLI 构建产物（bin 指向，git 忽略，npm pack 时包含）
+samples/      # 样例：sample.md（输入）、smaple.html（目标风格）、主题清单等
+```
+
+## 工作原理
+
+1. **预处理**：代码块、行内代码、`$$` 公式、`==` 高亮被提取为私有区占位符并预渲染，
+   避免代码块内的特殊字符被公式/高亮正则误伤。
+2. **解析**：用 `marked` 的 `lexer` 产出 GFM token 树。
+3. **渲染**：自研递归渲染器逐 token 输出**内联样式** HTML（微信编辑器只保留内联样式并过滤 `<style>`），
+   颜色全部来自当前主题的 light/dark 配色变量。
+4. 还原占位符，包一层正文容器后输出完整 HTML 文档。
+
+## 主题扩展
+
+在 `src/themes.ts` 的 `THEMES` 数组中新增一项即可：
+
+```ts
+{ name: '墨青', primary: '#00695C', desc: '沉稳墨青色', paper: '#F5F7F2' }
+```
+
+- `primary` 必填，其余颜色自动派生
+- `paper` 可选，浅色模式下正文默认纸张色
+- 深色模式下文字/卡片/边框自动反转，无需单独配置
+
+## 已知限制
+
+- KaTeX 渲染依赖 katex.css（公式的字体与精确字形），本地预览已自动注入 CDN 样式；
+  粘贴到公众号后 `<style>`/外链样式会被过滤，公式退化为 MathML/近似排版，建议公众号文章使用默认 `plain` 模式。
+- 代码卡片、引用等富样式为微信编辑器可识别的内联样式；个别旧版编辑器可能有细微差异。
+
+## Roadmap
+
+- [x] 深浅两套配色 + 可配置纸张色
+- [x] `--copy` 剪贴板复制、目录批量转换
+- [x] 本地图片 base64 内嵌、KaTeX 公式渲染
+- [ ] 表格深浅配色方案微调、`==` 高亮支持嵌套标记
+- [ ] 图床上传（腾讯云/七牛等）