Skip to content

README.zh.md

Latest commit

 

History

History
172 lines (97 loc) · 6.22 KB

README.zh.md

File metadata and controls

172 lines (97 loc) · 6.22 KB

English | 中文

Kup

Kup logo

A CLI tool to sync local Markdown files and GitHub issues bidirectionally.

一款命令行工具，实现本地 Markdown 文件与 GitHub Issues 的双向同步。

谁需要它

  • 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。
  • 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。
  • 其它需要频繁更新 GitHub issue 的人。

安装

npm install -g kup-cli

需要全局安装，以便随时在命令行调用。（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）

使用方法

发布新 issue

kup ./path/to/file.md --repo foo/bar

Kup 会把 file.md 文件的内容发布为 foo/bar 仓库的一个新 issue，发布成功后会告知新 issue 的编号。

更新已有 issue

kup ./path/to/file.md --repo foo/bar --id 123

Kup 会把 file.md 文件的内容更新到 foo/bar 仓库的编号为 123 的 issue。

采集已有 issue

kup --dump --repo foo/bar --id 123

Kup 会把 foo/bar 仓库的编号为 123 的 issue 采集为当前目录下的 123.md 文件。

如果你想指定输出文件，也可以这样使用：

kup ./path/to/file.md --dump --repo foo/bar --id 123

准备工作

操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。

  1. 在 GitHub 的 “Personal access tokens” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 这篇文档。）

  2. 把获取到的 token 写入环境变量：

    export GITHUB_TOKEN=ghp_**********

如果 Kup 未能从环境变量获取 token，会在命令行向你询问。

命令行参数

参数 短名 值类型 含义
--repo -r 字符串 指定 GitHub 仓库
--id -i 整数 指定 issue 的编号：
  • 指定编号表示更新已有 issue
  • 未指定编号则表示发布新 issue
--dump -d - 激活采集模式，把 GitHub issue 保存为本地 Markdown 文件
--version -v - 显示版本号
--help -h - 显示帮助信息

进阶

如何更方便地指定 repo 参数？

有以下方式可以指定 repo 参数，优先级递减：

  1. 调用命令行时指定的 --repo 参数。
  2. Markdown 文件内的 元数据 的 repo 字段。
  3. 当前项目的 package.json 文件内的 kup.repo 字段。Kup 会以 Markdown 文件所在目录为起点逐级向上寻找 package.json 文件。
  4. 如果 package.json 文件内没有 kup.repo 字段，则 Kup 会尝试根据 repository 字段来猜测仓库名（在使用前会向用户确认）。
  5. 如果以上方式都没有成功，则 Kup 会继续查找同级或上级目录中的 .git/config 文件，并尝试根据其中 remote "origin" 的 url 字段来猜测仓库名（在使用前会向用户确认）。

如果整个项目的同步目标都是同一个仓库，通常建议在 package.json 里统一配置 kup.repo。

如何更方便地指定 id 参数？

有以下方式可以指定 id 参数，优先级递减：

  1. 调用命令行时指定的 --id 参数。
  2. Markdown 文件内的元数据的 id 字段。

当一个文件成功发布为 issue 后，Kup 会把 id 写回文件的元数据中（在写入前会向用户确认）。

Issue 的标题是如何确定的？

Kup 会通过以下线索来确定 issue 的标题，优先级递减：

  1. Markdown 文件内的元数据的 title 字段。
  2. Markdown 正文的第一个标记如果是一级标题（# Title 格式），则取它的内容（在这种情况下，这个一级标题在同步时会从内容中排除）。

如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？

  • 如果是在发布新 issue，则 Kup 会自己生成一个标题。
  • 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。

如何为 issue 指定 label？

不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。因此 Kup 也实现了这个功能。

你需要在 Markdown 文件的元数据中添加 tags 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。

如果元数据中没有 tags 字段，Kup 会怎么处理？

  • 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。
  • 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。

在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。

文档

其它

开发计划

关于名字

  • Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。
  • Kup 是变形金刚人物 “杯子” 的英文名。

关于 Logo

License

Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.

任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。

MIT