share-pages 0.2.0 → 0.4.0

package/README.md

@@ -1,21 +1,40 @@
 # share-pages
 
-Share Pages 的命令行客户端，用于发布和管理 HTML、目录、Markdown、LaTeX、EPUB 与 CSV 内容。
+Share Pages 的命令行客户端，用于发布和管理 HTML、目录、Markdown、MDX、LaTeX、EPUB 与 CSV 内容。
+
+CLI 校验并上传原件，服务器提供阅读器。目录、搜索、阅读设置和 MDX 的 React 交互会跟随站点更新；本机无需安装 React 或携带阅读器字体、脚本。CLI 的格式校验和发布协议则随 npm 版本更新。
+
+默认输出为适合人阅读的摘要；添加 `--json` 可获得稳定的单行 JSON。直接运行 `share-pages`，或在任意命令后添加 `--help`，即可看到按工作流组织的示例。
 
 ## 安装
 
-需要 Node.js 22 或更高版本。
+需要 Node.js 22.18 或更高版本。运行依赖已随包提供，安装后无需额外构建。
 
 ```sh
 npm install --global share-pages
+share-pages --version
+share-pages
 ```
 
+也可直接使用 `npx share-pages@latest --help` 或 `pnpm dlx share-pages@latest`。
+
+## 强制自动更新
+
+每次启动都先通过 npm 实时检查 `latest`，包括无参数、`--help`、`--version`、登录、退出登录和 `--dry-run`。发现更高版本会自动安装并用新版继续原命令，不提供跳过检查或更新的选项；CI 和 `--no-interactive` 同样执行。
+
+新版安装在用户缓存（默认 `~/.cache/share-pages/cli`，可用 `XDG_CACHE_HOME` 指定；Windows 默认使用 `LOCALAPPDATA`）。全局、本地、npx 和 pnpm 安装入口均会转交给缓存中的新版，不改项目依赖、锁文件或原来的安装目录。因此锁定安装版本也不会锁定实际执行版本；当前版本高于 registry 的 `latest` 时不会降级。
+
+检查失败、安装失败或新版要求更高的 Node.js 时，原命令不会执行，退出码为 5；需要联网和可用的 npm。更新信息写入 stderr，`--quiet` 只隐藏进度，`--json` 保持单行 JSON。原命令的参数、当前目录和 stdin 会交给新版。`--dry-run` 不访问 Share Pages 实例，但仍必须检查 npm 更新。
+
+更新沿用 npm 的 registry、代理和用户认证配置，可通过 `npm config set registry <地址>` 或 `npm_config_registry` 指定源。源码开发也会检查；测试使用本地 npm registry 验证真实更新流程。
+
 ## 登录
 
 在 Share Pages 后台创建发布 Token，然后保存实例配置：
 
 ```sh
 share-pages login --server https://pages.example.com
+share-pages status
 ```
 
 自动化环境可通过 stdin 提供 Token：
@@ -32,13 +51,55 @@ printf '%s' "$SHARE_PAGES_TOKEN" | share-pages login \
 ```sh
 share-pages publish ./site --id docs
 share-pages publish ./README.md --id readme --access public
+share-pages publish ./lesson.mdx --id lesson
 share-pages publish ./report.csv --id report --title "Report"
 ```
 
-发布前只做本地转换和校验：
+MDX 支持 JSX、表达式、`import` / `export`、React 组件、Hooks 与事件。带本地 TSX、MDX、CSS、JSON 或图片导入时，发布包含入口和依赖的目录或 ZIP：
+
+```sh
+share-pages publish ./lesson --id lesson
+share-pages publish ./lesson.mdx.zip --id lesson
+share-pages publish ./lesson.zip --type mdx --entry docs/index.mdx --id lesson
+printf '# MDX\n\n{6 * 7}\n' | share-pages publish - --type mdx --id example
+```
+
+目录中的 `index.md` / `index.mdx` 会自动识别。单文件不会自动收集相邻依赖。Markdown/MDX 支持 Frontmatter、公式、代码高亮与行高亮；自定义 npm 组件通过 esm.sh 在浏览器加载，需要支持浏览器环境。
+
+成功后 CLI 会给出页面地址、管理入口和下一次更新命令。更新已有页面必须显式添加 `--update`，避免误操作：
+
+```sh
+share-pages publish ./README.md --id readme --update
+```
+
+发布前只做本地校验，不需要登录或网络：
 
 ```sh
 share-pages publish ./site --dry-run --json
+share-pages publish ./lesson.mdx --dry-run --json
+```
+
+## 查询与恢复
+
+```sh
+share-pages pages list
+share-pages pages get readme
+share-pages versions list readme
+share-pages stats readme
+share-pages download readme --output readme-original.md
+```
+
+网络中断后，使用首次上传时打印的会话 ID 继续：
+
+```sh
+share-pages publish ./site --id docs --resume <upload-id>
+share-pages uploads <upload-id>
+```
+
+删除本机凭据不会撤销远端 Token；敏感 Token 仍应在后台撤销：
+
+```sh
+share-pages logout
 ```
 
 查看全部命令：
@@ -47,3 +108,7 @@ share-pages publish ./site --dry-run --json
 share-pages --help
 share-pages publish --help
 ```
+
+完整参数、约束和示例均可通过 `share-pages help <命令>` 查看；显示帮助前也会完成强制更新检查。
+
+完整指南：[CLI](https://github.com/Lakphy/share-pages/blob/main/docs/cli-guide.md) · [MDX](https://github.com/Lakphy/share-pages/blob/main/docs/mdx.md)。程序化发布使用 `@share-pages/content/node` 和 `@share-pages/sdk`。